@jungjaehoon/mama-core 5.0.0 → 5.2.0

package/README.md

@@ -4,7 +4,7 @@ The shared engine for storage, records and revisions, evidence links, memory, se
 runtime drivers. Consumers supply their own database, principals, source access and product
 vocabulary through public exports. Core does not require the MAMA OS daemon.
 
-Version **5.0.0**; Node.js 22.13+. This README describes the current rebuild checkout.
+Version **5.2.0**; Node.js 22.13+. This README describes the current rebuild checkout.
 See [architecture](../../docs/explanation/architecture.md) and
 [the shared-engine goal](../../INTENT.md).
 

package/dist/api/catalog.js

@@ -1367,7 +1367,7 @@ function coreActionRegistrations(knowledge, adapter, deps) {
                     memoryId: typeof body.memory_id === 'string' ? body.memory_id : '',
                     status,
                     reason: typeof body.reason === 'string' ? body.reason : '',
-                }, { ...writeAccess, scopes }, requiredOperationId(context, 'memory.retire'));
+                }, { ...writeAccess, scopes }, requiredOperationId(context, 'memory.retire'), context.session);
                 recordWriteReceipt(context, 'memory.retire', retired.id);
                 return retired;
             },

package/dist/knowledge/access.js

@@ -17,7 +17,7 @@ const tableColumnCache = new WeakMap();
 // Keep memory-truth quarantine semantics excluded for legacy/backcompat rows even though the
 // decisions.status terminal states: 'superseded' is history a caller holding
 // scope may read under includeReplaced; the rest are holds excluded always.
-const RETIRED_MEMORY_STATUSES = new Set(['quarantined', 'contradicted', 'stale']);
+const RETIRED_MEMORY_STATUSES = new Set(['contradicted', 'stale']);
 class TwinRefNotVisibleError extends Error {
     constructor(ref) {
         super(`Twin ref is not visible to requested visibility: ${ref.kind}:${ref.id}`);

package/dist/knowledge/index.d.ts

@@ -19,7 +19,7 @@ export { observationVersionId, appendObservationVersion, getObservationVersion,
 export { createWork, readWork, reviseWork, withdrawWork } from './commitments.js';
 export { parseExactDueAt, assertIsoDate, assertWorkPatchValues, WORK_PATCH_DEADLINE_PATTERN, WORK_PATCH_DUE_AT_PATTERN, type ParsedExactDueAt, } from './work-dates.js';
 export type { CommitmentPage, CommitmentChainEntry, CommitmentRevision, CommitmentView, CreateWorkCommand, ReviseWorkCommand, WithdrawWorkCommand, WorkRead, WorkWriteResult, } from './commitments.js';
-export { vectorSearch, fts5Search } from './search.js';
+export { vectorSearch, fts5Search, RECALL_EXCLUDED_STATUSES } from './search.js';
 export { queryDecisionGraph, querySemanticEdges, STATED_DECISION_EDGES, getGraphNeighborhood, getGraphPaths, getGraphTimeline, queryGraph, AgentGraphValidationError, type AgentGraphAdapter, type AgentGraphEdgeFilters, type AgentGraphResult, type AgentGraphCurrentProjection, type AgentGraphPath, type AgentGraphTimelineEvent, type AgentGraphTimelineMemoryEvent, type AgentGraphTimelineCaseEvent, type AgentGraphTimelineRawEvent, type AgentGraphTimelineEdgeEvent, type GraphNeighborhoodInput, type GraphPathsInput, type GraphPathsResult, type GraphTimelineInput, type GraphTimelineResult, } from './graph-query.js';
 export type { SourceIngestCommand, SourceIngestReceipt } from './source-ingest.js';
 export interface KnowledgeOptions extends JudgmentKnowledgeOptions {

package/dist/knowledge/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentGraphValidationError = exports.queryGraph = exports.getGraphTimeline = exports.getGraphPaths = exports.getGraphNeighborhood = exports.STATED_DECISION_EDGES = exports.querySemanticEdges = exports.queryDecisionGraph = exports.fts5Search = exports.vectorSearch = exports.WORK_PATCH_DUE_AT_PATTERN = exports.WORK_PATCH_DEADLINE_PATTERN = exports.assertWorkPatchValues = exports.assertIsoDate = exports.parseExactDueAt = exports.withdrawWork = exports.reviseWork = exports.readWork = exports.createWork = exports.isObservationVisibilityRowVisible = exports.isObservationVersionVisible = exports.readObservationVersion = exports.searchOwnerObservationVersions = exports.getObservationVersion = exports.appendObservationVersion = exports.observationVersionId = exports.correctIdentity = exports.ingestSource = exports.TWIN_REF_KINDS = exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.TwinRefNotVisibleError = exports.visibleTwinRefKeysRecursive = exports.visibleTwinRefKeys = exports.listVisibleTwinEdgesForRefs = exports.isChannelGranted = exports.channelGrantClause = exports.assertTwinRefsVisible = exports.linkEdgeId = exports.findLink = exports.appendLink = exports.mapTwinEdgeRow = exports.listTwinEdgesForRefs = exports.getTwinEdge = exports.appendJudgment = exports.JudgmentError = exports.WORK_RECLASSIFY_DISPOSITIONS = exports.judgmentRecordId = void 0;
+exports.AgentGraphValidationError = exports.queryGraph = exports.getGraphTimeline = exports.getGraphPaths = exports.getGraphNeighborhood = exports.STATED_DECISION_EDGES = exports.querySemanticEdges = exports.queryDecisionGraph = exports.RECALL_EXCLUDED_STATUSES = exports.fts5Search = exports.vectorSearch = exports.WORK_PATCH_DUE_AT_PATTERN = exports.WORK_PATCH_DEADLINE_PATTERN = exports.assertWorkPatchValues = exports.assertIsoDate = exports.parseExactDueAt = exports.withdrawWork = exports.reviseWork = exports.readWork = exports.createWork = exports.isObservationVisibilityRowVisible = exports.isObservationVersionVisible = exports.readObservationVersion = exports.searchOwnerObservationVersions = exports.getObservationVersion = exports.appendObservationVersion = exports.observationVersionId = exports.correctIdentity = exports.ingestSource = exports.TWIN_REF_KINDS = exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.TwinRefNotVisibleError = exports.visibleTwinRefKeysRecursive = exports.visibleTwinRefKeys = exports.listVisibleTwinEdgesForRefs = exports.isChannelGranted = exports.channelGrantClause = exports.assertTwinRefsVisible = exports.linkEdgeId = exports.findLink = exports.appendLink = exports.mapTwinEdgeRow = exports.listTwinEdgesForRefs = exports.getTwinEdge = exports.appendJudgment = exports.JudgmentError = exports.WORK_RECLASSIFY_DISPOSITIONS = exports.judgmentRecordId = void 0;
 exports.createKnowledge = createKnowledge;
 const links_js_1 = require("./links.js");
 const judgments_js_1 = require("./judgments.js");
@@ -62,6 +62,7 @@ Object.defineProperty(exports, "WORK_PATCH_DUE_AT_PATTERN", { enumerable: true,
 var search_js_1 = require("./search.js");
 Object.defineProperty(exports, "vectorSearch", { enumerable: true, get: function () { return search_js_1.vectorSearch; } });
 Object.defineProperty(exports, "fts5Search", { enumerable: true, get: function () { return search_js_1.fts5Search; } });
+Object.defineProperty(exports, "RECALL_EXCLUDED_STATUSES", { enumerable: true, get: function () { return search_js_1.RECALL_EXCLUDED_STATUSES; } });
 var graph_query_js_2 = require("./graph-query.js");
 Object.defineProperty(exports, "queryDecisionGraph", { enumerable: true, get: function () { return graph_query_js_2.queryDecisionGraph; } });
 Object.defineProperty(exports, "querySemanticEdges", { enumerable: true, get: function () { return graph_query_js_2.querySemanticEdges; } });

package/dist/knowledge/search.d.ts

@@ -8,6 +8,8 @@
  */
 import type { DatabaseInstance, DecisionRecord } from '../db-manager.js';
 import type { MemoryKindFilter } from '../memory/types.js';
+/** Statuses default recall leaves out; history (`includeHistory`) shows them. */
+export declare const RECALL_EXCLUDED_STATUSES: readonly ["superseded", "contradicted", "stale"];
 /**
  * Brute-force cosine similarity search over stored embeddings.
  *
@@ -31,7 +33,10 @@ export declare function vectorSearch(adapter: DatabaseInstance, queryEmbedding:
  * @param limit - Max rows to return
  * @returns Matching decision IDs with BM25 rank scores
  */
-export declare function fts5Search(adapter: DatabaseInstance, query: string, limit?: number, kind?: MemoryKindFilter): Promise<{
+export declare function fts5Search(adapter: DatabaseInstance, query: string, limit?: number, kind?: MemoryKindFilter, exclude?: {
+    statuses?: readonly string[];
+    amendments?: boolean;
+}): Promise<{
     id: string;
     rank: number;
 }[]>;

package/dist/knowledge/search.js

@@ -8,8 +8,11 @@
  * @module knowledge/search
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECALL_EXCLUDED_STATUSES = void 0;
 exports.vectorSearch = vectorSearch;
 exports.fts5Search = fts5Search;
+/** Statuses default recall leaves out; history (`includeHistory`) shows them. */
+exports.RECALL_EXCLUDED_STATUSES = ['superseded', 'contradicted', 'stale'];
 /**
  * Brute-force cosine similarity search over stored embeddings.
  *
@@ -59,7 +62,7 @@ async function vectorSearch(adapter, queryEmbedding, limit = 5, threshold = 0.7,
  * @param limit - Max rows to return
  * @returns Matching decision IDs with BM25 rank scores
  */
-async function fts5Search(adapter, query, limit = 10, kind) {
+async function fts5Search(adapter, query, limit = 10, kind, exclude) {
     // An absent FTS table is a real answer - no rows. A failing adapter is not,
     // so this lookup is left unguarded and its errors reach the caller.
     const tableCheck = adapter
@@ -68,24 +71,27 @@ async function fts5Search(adapter, query, limit = 10, kind) {
     if (!tableCheck)
         return [];
     // Query execution - let errors propagate to the caller
-    const kindClause = Array.isArray(kind)
-        ? `AND d.kind IN (${kind.map(() => '?').join(', ')})`
-        : kind === undefined
-            ? ''
-            : 'AND d.kind = ?';
+    const kinds = Array.isArray(kind) ? kind : kind === undefined ? [] : [kind];
+    const kindClause = kinds.length === 0 ? '' : `AND d.kind IN (${kinds.map(() => '?').join(', ')})`;
+    // Excluded rows are left out before LIMIT, so they cannot fill the pool ahead of rows that stay.
+    const statuses = exclude?.statuses ?? [];
+    const statusClause = statuses.length === 0
+        ? ''
+        : `AND (d.status IS NULL OR d.status NOT IN (${statuses.map(() => '?').join(', ')}))`;
+    const amendmentClause = exclude?.amendments
+        ? "AND json_extract(d.payload_json, '$.amended') IS NULL"
+        : '';
     const stmt = adapter.prepare(`
     SELECT d.id, rank
     FROM decisions_fts
     JOIN decisions d ON decisions_fts.rowid = d.rowid
     WHERE decisions_fts MATCH ?
       ${kindClause}
+      ${statusClause}
+      ${amendmentClause}
     ORDER BY rank
     LIMIT ?
   `);
-    return (Array.isArray(kind)
-        ? stmt.all(query, ...kind, limit)
-        : kind === undefined
-            ? stmt.all(query, limit)
-            : stmt.all(query, kind, limit));
+    return stmt.all(query, ...kinds, ...statuses, limit);
 }
 //# sourceMappingURL=search.js.map

package/dist/memory/api.d.ts

@@ -30,6 +30,8 @@ export declare function buildDecisionId(topic: string): string;
 export interface ReadMemoryRecordsOptions {
     kind?: MemoryKindFilter;
     status?: MemoryStatus | readonly MemoryStatus[];
+    /** Leave out records that only amend another (a retirement or an outcome change), as recall does. */
+    excludeAmendments?: boolean;
 }
 /** Read complete memory records whose stored scopes intersect the admitted scopes. */
 export declare function readMemoryRecordsInScopes(adapter: DatabaseInstance, scopes: readonly MemoryScopeRef[], options?: ReadMemoryRecordsOptions): Promise<MemoryRecord[]>;
@@ -76,7 +78,7 @@ 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;

package/dist/memory/api.js

@@ -167,6 +167,9 @@ async function readMemoryRecordsInScopes(adapter, scopes, options = {}) {
         conditions.push(`COALESCE(d.status, 'active') IN (${statuses.map(() => '?').join(', ')})`);
         params.push(...statuses);
     }
+    if (options.excludeAmendments === true) {
+        conditions.push(`json_extract(d.payload_json, '$.amended') IS NULL`);
+    }
     const rows = adapter
         .prepare(`SELECT d.id, d.topic, d.decision, d.reasoning, d.confidence, d.created_at, d.updated_at,
               d.trust_context, d.kind, d.status, d.summary, d.event_date, d.event_datetime,
@@ -713,7 +716,7 @@ async function saveLegacyMemory(adapter, input, legacy, access) {
     return saveMemoryInternal(adapter, clean, provenance, effectiveAccess, legacy);
 }
 /** Append an access-checked status amendment for one stored memory record. */
-async function retireMemoryRecord(adapter, input, access, commandId) {
+async function retireMemoryRecord(adapter, input, access, commandId, session) {
     const id = input.memoryId.trim();
     const reason = input.reason.trim();
     if (!id)
@@ -729,11 +732,30 @@ async function retireMemoryRecord(adapter, input, access, commandId) {
     }
     const admittedScopes = record.scopes.filter((recordScope) => access.scopes.some((scope) => scope.kind === recordScope.kind && scope.id === recordScope.id));
     const summary = `Status '${input.status}' applied to ${id}: ${reason}`;
+    // Who retired it, stated by the host as for a save, so a retirement can be traced to its turn.
+    const provenance = (0, provenance_js_1.normalizeMemoryWriteProvenance)({
+        actor: session?.actor ?? 'main_agent',
+        agent_id: access.agentId,
+        model_run_id: session?.modelRunId,
+        envelope_hash: session?.envelopeHash,
+        tool_name: session?.toolName,
+        gateway_call_id: session?.gatewayCallId,
+        context_packet_id: session?.contextPacketId,
+        source_turn_id: session?.sourceTurnId,
+        source_message_ref: session?.sourceMessageRef,
+        source_refs: session?.sourceRefs ? [...session.sourceRefs] : undefined,
+    });
     const receipt = await (0, index_js_1.appendJudgment)({
         commandId,
         topic: `judgment/${id}`,
         summary,
         recordKind: 'judgment',
+        sourceRefs: provenance.source_refs,
+        provenance: provenance.provenance,
+        agentId: provenance.agent_id,
+        modelRunId: provenance.model_run_id,
+        envelopeHash: provenance.envelope_hash,
+        gatewayCallId: provenance.gateway_call_id,
         payload: { amended: id, status: input.status, reason },
         scopes: admittedScopes,
         links: [{ relation: 'amends', target: { kind: 'memory', id } }],
@@ -747,12 +769,15 @@ async function buildProfile(adapter, scopes) {
     const records = await loadScopedMemories(adapter, scopes);
     return (0, profile_builder_js_1.classifyProfileEntries)(records);
 }
-const EXCLUDED_STATUSES = new Set([
-    'superseded',
-    'quarantined',
-    'contradicted',
-    'stale',
-]);
+const EXCLUDED_STATUSES = new Set(search_js_1.RECALL_EXCLUDED_STATUSES);
+/** The ids among these that only amend another record (a retirement or an outcome change). */
+function amendmentIds(adapter, ids) {
+    const rows = adapter
+        .prepare(`SELECT id FROM decisions WHERE id IN (${ids.map(() => '?').join(',')})
+         AND json_extract(payload_json, '$.amended') IS NOT NULL`)
+        .all(...ids);
+    return new Set(rows.map((row) => row.id));
+}
 async function recallMemory(adapter, query, options = {}) {
     const bundle = (0, types_js_1.createEmptyRecallBundle)(query);
     const searchOptions = (0, search_quality_js_1.normalizeSearchQualityOptions)(options);
@@ -930,7 +955,7 @@ async function recallMemory(adapter, query, options = {}) {
                 .map((t) => stemToken(t))
                 .filter((t) => !FTS5_NOISE_WORDS.has(t));
             const ftsQuery = ftsTokens.length > 0 ? ftsTokens.join(' OR ') : query;
-            const ftsResults = await (0, search_js_1.fts5Search)(searchAdapter, ftsQuery, lexicalLimit, options.kind);
+            const ftsResults = await (0, search_js_1.fts5Search)(searchAdapter, ftsQuery, lexicalLimit, options.kind, options.includeHistory ? undefined : { statuses: [...EXCLUDED_STATUSES], amendments: true });
             if (ftsResults.length > 0) {
                 const adapter = searchAdapter;
                 const fallbackSource = {
@@ -1012,6 +1037,10 @@ async function recallMemory(adapter, query, options = {}) {
             if (options.kind !== undefined) {
                 lexicalRecords = lexicalRecords.filter((r) => matchesKind(r.kind));
             }
+            if (!options.includeHistory && lexicalRecords.length > 0) {
+                const amendments = amendmentIds(adapter, lexicalRecords.map((r) => r.id));
+                lexicalRecords = lexicalRecords.filter((r) => !amendments.has(r.id));
+            }
             lexicalCandidates = buildLexicalCandidates(lexicalRecords, query);
             if (subQueries.length > 1) {
                 for (const sq of subQueries.slice(1)) {
@@ -1187,6 +1216,15 @@ async function recallMemory(adapter, query, options = {}) {
         ];
     });
     fusedHits = fusedHits.filter((hit) => hit.source_type !== 'decision' || acceptedPrimaryIds.has(hit.source_id));
+    // A retirement or an outcome change audits another record; it is not a belief. Default recall
+    // leaves it out and history shows it. Only the host writers put `amended` in a payload.
+    if (!options.includeHistory && matched.length > 0) {
+        const amendments = amendmentIds(adapter, matched.map((record) => record.id));
+        if (amendments.size > 0) {
+            matched = matched.filter((record) => !amendments.has(record.id));
+            fusedHits = fusedHits.filter((hit) => hit.source_type !== 'decision' || !amendments.has(hit.source_id));
+        }
+    }
     // Honor options.limit on the final memories (matched is RRF-rank-sorted, canonical
     // dual-write appends last). Without this cap the full fusion set (hundreds of records)
     // flowed into bundle.memories AND the per-record enrichment SQL loops below.
@@ -1198,14 +1236,20 @@ async function recallMemory(adapter, query, options = {}) {
         const cappedIds = new Set(matched.map((record) => record.id));
         fusedHits = fusedHits.filter((hit) => hit.source_type !== 'decision' || cappedIds.has(hit.source_id));
     }
-    // Enrich active records with summaries from their superseded predecessors.
-    // When ingestConversation extracts multiple facts under the same topic, only
-    // the last survives as "active" — the earlier ones become superseded and are
-    // excluded from search.  This recovers their key information so it is not lost.
+    // Superseded records are excluded from search, so an active record carries what it replaced:
+    // the reader sees the correction and what it corrected. A predecessor is shown only inside the
+    // reader's scopes, and marked as replaced.
     if (matched.length > 0) {
         const stmtChain = adapter.prepare(`SELECT id, summary, decision FROM decisions WHERE superseded_by = ?`);
+        const readerScopes = options.scopes && options.scopes.length > 0
+            ? new Set(options.scopes.map((scope) => `${scope.kind}:${scope.id}`))
+            : null;
         for (const record of matched) {
-            const predecessors = stmtChain.all(record.id);
+            let predecessors = stmtChain.all(record.id);
+            if (readerScopes && predecessors.length > 0) {
+                const scopeMap = batchLoadScopes(adapter, predecessors.map((predecessor) => predecessor.id));
+                predecessors = predecessors.filter((predecessor) => (scopeMap.get(predecessor.id) ?? []).some((scope) => readerScopes.has(`${scope.kind}:${scope.id}`)));
+            }
             if (predecessors.length > 0) {
                 const extra = predecessors
                     .map((p) => String(p.summary ?? p.decision ?? ''))
@@ -1213,8 +1257,8 @@ async function recallMemory(adapter, query, options = {}) {
                     .join(' | ');
                 if (extra) {
                     record.details = record.details
-                        ? `${record.details}\n[Prior context] ${extra}`
-                        : `[Prior context] ${extra}`;
+                        ? `${record.details}\n[Replaced by this record] ${extra}`
+                        : `[Replaced by this record] ${extra}`;
                 }
             }
         }
@@ -1243,6 +1287,11 @@ async function recallMemory(adapter, query, options = {}) {
                 const status = row?.status || '';
                 return matchesKind(row?.kind) && (!status || !EXCLUDED_STATUSES.has(status));
             });
+            // A link an agent stated can point at a retirement or an outcome change; it stays out too.
+            if (expandedOnly.length > 0) {
+                const amendments = amendmentIds(adapter, expandedOnly.map((e) => e.id));
+                expandedOnly = expandedOnly.filter((e) => !amendments.has(e.id));
+            }
         }
         else if (options.kind !== undefined) {
             expandedOnly = expandedOnly.filter((e) => {

package/dist/memory/provenance-live.js

@@ -24,7 +24,7 @@ exports.OBSERVATION_COLUMNS = `observation_id AS event_index_id, source AS sourc
  * Statuses every memory read path excludes (source-readers.ts:293, and recall's own
  * history exclusion). Mirrored so a citation cannot present a retired record as current.
  */
-const RETIRED_MEMORY_STATUSES = new Set(['superseded', 'quarantined', 'contradicted', 'stale']);
+const RETIRED_MEMORY_STATUSES = new Set(['superseded', 'contradicted', 'stale']);
 /**
  * Parse a stored source ref into what it actually is.
  *

package/dist/memory/types.d.ts

@@ -29,7 +29,7 @@ export type MemoryKind = (typeof MEMORY_KINDS)[number];
 export type MemoryKindFilter = MemoryKind | [MemoryKind, ...MemoryKind[]];
 export declare const MEMORY_STATUSES: readonly ["active", "superseded", "contradicted", "stale"];
 export type MemoryStatus = (typeof MEMORY_STATUSES)[number];
-export declare const MEMORY_TRUTH_STATUSES: readonly ["active", "superseded", "contradicted", "stale", "quarantined"];
+export declare const MEMORY_TRUTH_STATUSES: readonly ["active", "superseded", "contradicted", "stale"];
 export type MemoryTruthStatus = (typeof MEMORY_TRUTH_STATUSES)[number];
 export declare const MEMORY_EDGE_TYPES: readonly ["supersedes", "builds_on", "synthesizes", "contradicts"];
 export type MemoryEdgeType = (typeof MEMORY_EDGE_TYPES)[number];

package/dist/memory/types.js

@@ -35,13 +35,7 @@ exports.MEMORY_KINDS = [
     'workflow',
 ];
 exports.MEMORY_STATUSES = ['active', 'superseded', 'contradicted', 'stale'];
-exports.MEMORY_TRUTH_STATUSES = [
-    'active',
-    'superseded',
-    'contradicted',
-    'stale',
-    'quarantined',
-];
+exports.MEMORY_TRUTH_STATUSES = ['active', 'superseded', 'contradicted', 'stale'];
 exports.MEMORY_EDGE_TYPES = ['supersedes', 'builds_on', 'synthesizes', 'contradicts'];
 exports.MEMORY_AGENT_ACTIONS = [
     'save',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-core",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "MAMA Core - Shared modules for Memory-Augmented MCP Assistant",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",