@graphorin/memory 0.5.0

package/dist/consolidator/reconcile.js

@@ -0,0 +1,192 @@
+import { enLocalePack } from "../conflict/locale-packs/en.js";
+import "../conflict/locale-packs/index.js";
+import { stage1ExactDedup } from "../conflict/stages/stage1-exact-dedup.js";
+import { stage2EmbeddingThreeZone } from "../conflict/stages/stage2-embedding-three-zone.js";
+import { DEFAULT_CONFLICT_THRESHOLDS } from "../conflict/types.js";
+import "../conflict/index.js";
+
+//#region src/consolidator/reconcile.ts
+/**
+* Classify a candidate against its nearest neighbours using the conflict
+* pipeline's first two (cheap, LLM-free) stages. Reuses
+* {@link stage1ExactDedup} + {@link stage2EmbeddingThreeZone} verbatim so
+* the zone thresholds stay aligned with the inline write path.
+*
+* @stable
+*/
+async function preFilterCandidate(candidateText, neighbors, opts = {}) {
+	const thresholds = opts.thresholds ?? DEFAULT_CONFLICT_THRESHOLDS;
+	const localePack = opts.localePack ?? enLocalePack;
+	const ctx = {
+		candidate: synthCandidate(candidateText),
+		existing: neighbors,
+		localePack,
+		thresholds
+	};
+	const s1 = await stage1ExactDedup.evaluate(ctx);
+	if (s1.kind === "dedup") return {
+		route: "noop",
+		targetId: s1.existingId,
+		...s1.similarity !== void 0 ? { similarity: s1.similarity } : {},
+		reason: s1.reason ?? "exact-hash-match"
+	};
+	const s2 = await stage2EmbeddingThreeZone.evaluate(ctx);
+	if (s2.kind === "dedup") return {
+		route: "noop",
+		targetId: s2.existingId,
+		...s2.similarity !== void 0 ? { similarity: s2.similarity } : {},
+		reason: s2.reason ?? "embedding-zone"
+	};
+	if (s2.kind === "admit") return {
+		route: "add",
+		reason: s2.reason ?? "embedding-cold-zone"
+	};
+	return { route: "reconcile" };
+}
+/**
+* System prompt for the reconcile pass. Mirrors the deep-phase judge
+* style but expands the decision space to the full ADD/UPDATE/NOOP/
+* CONFLICT loop and asks for the `targetId` of the resolved neighbour.
+*
+* @internal
+*/
+const RECONCILE_SYSTEM_PROMPT = [
+	"You reconcile a candidate memory against the user's existing related memories.",
+	"Return strictly JSON: { \"action\": \"add\" | \"update\" | \"noop\" | \"conflict\", \"targetId\"?: string, \"reason\": string }.",
+	"Use \"update\" when the candidate is a newer version of an existing memory (a changed preference, location, job, or fact).",
+	"Use \"noop\" when the candidate adds nothing new (a duplicate or subset of an existing memory).",
+	"Use \"conflict\" when the candidate contradicts an existing memory and the older one should be closed.",
+	"Use \"add\" when the candidate is independent of every listed memory, or when you are unsure.",
+	"For \"update\", \"noop\", and \"conflict\", set \"targetId\" to the id of the existing memory you are resolving against."
+].join(" ");
+/**
+* Run one reconcile pass. The decision is always safe to apply: parse
+* failures and dangling `targetId`s degrade to an additive write.
+*
+* @stable
+*/
+async function reconcileCandidate(args) {
+	const request = buildReconcileRequest(args);
+	const response = await args.provider.generate(request);
+	const usage = response.usage;
+	const promptTokens = usage.promptTokens ?? 0;
+	const completionTokens = usage.completionTokens ?? 0;
+	const totalTokens = promptTokens + completionTokens + (usage.reasoningTokens ?? 0);
+	const validIds = new Set(args.neighbors.map((n) => n.id));
+	return {
+		decision: parseReconcile(response.text, validIds),
+		usage: {
+			promptTokens,
+			completionTokens,
+			totalTokens
+		}
+	};
+}
+/**
+* Parse the reconcile model output into a {@link ReconcileDecision}.
+* Tolerates fenced blocks + trailing commentary; an unparseable body,
+* an unknown action, or a `targetId` that is not in `validTargetIds`
+* all degrade to `{ action: 'add' }` (audited via the reason).
+*
+* @internal
+*/
+function parseReconcile(text, validTargetIds) {
+	const fallback = {
+		action: "add",
+		reason: "reconcile-parse-failure"
+	};
+	if (text === void 0 || text.length === 0) return fallback;
+	const candidate = stripFence(text).trim();
+	if (candidate.length === 0) return fallback;
+	let parsed;
+	try {
+		parsed = JSON.parse(candidate);
+	} catch {
+		const slice = sliceJsonObject(candidate);
+		if (slice === null) return fallback;
+		try {
+			parsed = JSON.parse(slice);
+		} catch {
+			return fallback;
+		}
+	}
+	if (parsed === null || typeof parsed !== "object") return fallback;
+	const obj = parsed;
+	const reason = typeof obj.reason === "string" && obj.reason.length > 0 ? obj.reason : void 0;
+	if (obj.action === "add") return {
+		action: "add",
+		...reason !== void 0 ? { reason } : {}
+	};
+	if (obj.action === "update" || obj.action === "noop" || obj.action === "conflict") {
+		const targetId = typeof obj.targetId === "string" ? obj.targetId : null;
+		if (targetId === null || !validTargetIds.has(targetId)) return {
+			action: "add",
+			reason: "reconcile-invalid-target"
+		};
+		if (obj.action === "noop") return {
+			action: "noop",
+			targetId,
+			...reason !== void 0 ? { reason } : {}
+		};
+		return {
+			action: obj.action,
+			targetId,
+			reason: reason ?? `reconcile-${obj.action}`
+		};
+	}
+	return fallback;
+}
+function buildReconcileRequest(args) {
+	const neighborLines = args.neighbors.map((n, i) => {
+		const vf = n.validFrom !== void 0 ? ` (validFrom: ${n.validFrom})` : "";
+		return `${i + 1}. [id: ${n.id}]${vf} ${n.text}`;
+	}).join("\n");
+	return {
+		messages: [{
+			role: "user",
+			content: [
+				`Candidate memory: ${args.candidateText}`,
+				"",
+				"Existing related memories:",
+				neighborLines.length > 0 ? neighborLines : "(none)"
+			].join("\n")
+		}],
+		systemMessage: RECONCILE_SYSTEM_PROMPT,
+		temperature: 0,
+		maxTokens: 256,
+		metadata: {
+			userId: args.scope.userId,
+			...args.scope.sessionId !== void 0 ? { sessionId: args.scope.sessionId } : {},
+			...args.scope.agentId !== void 0 ? { agentId: args.scope.agentId } : {}
+		},
+		outputType: { kind: "structured" }
+	};
+}
+/**
+* Minimal candidate `Fact` for the pre-filter stage context. Stage 1
+* reads only `text`; Stage 2 reads only the neighbour scores — the
+* other fields are never inspected, so a synthetic id/scope is safe.
+*/
+function synthCandidate(text) {
+	return {
+		id: "__reconcile_candidate__",
+		kind: "semantic",
+		userId: "__reconcile_candidate__",
+		sensitivity: "internal",
+		text,
+		createdAt: (/* @__PURE__ */ new Date(0)).toISOString()
+	};
+}
+function stripFence(text) {
+	return /^```[^\n]*\n([\s\S]*?)\n```/u.exec(text.trim())?.[1] ?? text;
+}
+function sliceJsonObject(text) {
+	const start = text.indexOf("{");
+	const end = text.lastIndexOf("}");
+	if (start < 0 || end < start) return null;
+	return text.slice(start, end + 1);
+}
+
+//#endregion
+export { preFilterCandidate, reconcileCandidate };
+//# sourceMappingURL=reconcile.js.map

package/dist/consolidator/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","names":["ctx: StageContext","fallback: ReconcileDecision","parsed: unknown"],"sources":["../../src/consolidator/reconcile.ts"],"sourcesContent":["/**\n * Neighbour-aware write reconciliation (P0-3) — the `reconcile` half of\n * Mem0's extract→reconcile loop (arXiv:2504.19413), with Graphorin's\n * bi-temporal twist.\n *\n * Two pieces live here:\n *\n *  - {@link preFilterCandidate} — a *cheap*, LLM-free classifier that\n *    reuses the conflict pipeline's Stage 1 (exact-dedup) + Stage 2\n *    (embedding three-zone) over the candidate's nearest neighbours.\n *    Clear hot / near-dup neighbours short-circuit to `noop`; a clearly\n *    cold field (or no neighbours at all) short-circuits to `add`. Only\n *    the ambiguous CONFLICT-CHECK mid-zone is routed to `reconcile`, so\n *    the consolidator spends an LLM call only where it actually helps.\n *\n *  - {@link reconcileCandidate} — one provider pass that, with the\n *    neighbours *in view*, chooses ADD / UPDATE / NOOP / CONFLICT.\n *    Parsing is defensive: malformed output, an unknown action, or a\n *    `targetId` that is not one of the supplied neighbours all fall back\n *    to a safe additive write (audited) so a flaky model never wedges\n *    the pipeline or rewrites the wrong fact.\n *\n * @packageDocumentation\n */\n\nimport type { Fact, MemoryHit, Provider, ProviderRequest, SessionScope } from '@graphorin/core';\nimport {\n  type ConflictThresholds,\n  DEFAULT_CONFLICT_THRESHOLDS,\n  type ReconcileDecision,\n  type StageContext,\n} from '../conflict/index.js';\nimport { enLocalePack, type LocalePack } from '../conflict/locale-packs/index.js';\nimport { stage1ExactDedup } from '../conflict/stages/stage1-exact-dedup.js';\nimport { stage2EmbeddingThreeZone } from '../conflict/stages/stage2-embedding-three-zone.js';\n\n/**\n * Pre-filter routing decision. `add` and `noop` are resolved without an\n * LLM call; `reconcile` means the candidate landed in the ambiguous\n * mid-zone and should be handed to {@link reconcileCandidate}.\n *\n * @stable\n */\nexport type PreFilterRoute =\n  | { readonly route: 'add'; readonly reason: string }\n  | {\n      readonly route: 'noop';\n      readonly targetId: string;\n      readonly similarity?: number;\n      readonly reason: string;\n    }\n  | { readonly route: 'reconcile' };\n\n/**\n * Classify a candidate against its nearest neighbours using the conflict\n * pipeline's first two (cheap, LLM-free) stages. Reuses\n * {@link stage1ExactDedup} + {@link stage2EmbeddingThreeZone} verbatim so\n * the zone thresholds stay aligned with the inline write path.\n *\n * @stable\n */\nexport async function preFilterCandidate(\n  candidateText: string,\n  neighbors: ReadonlyArray<MemoryHit<Fact>>,\n  opts: { readonly thresholds?: ConflictThresholds; readonly localePack?: LocalePack } = {},\n): Promise<PreFilterRoute> {\n  const thresholds = opts.thresholds ?? DEFAULT_CONFLICT_THRESHOLDS;\n  const localePack = opts.localePack ?? enLocalePack;\n  const ctx: StageContext = {\n    candidate: synthCandidate(candidateText),\n    existing: neighbors,\n    localePack,\n    thresholds,\n  };\n\n  const s1 = await stage1ExactDedup.evaluate(ctx);\n  if (s1.kind === 'dedup') {\n    return {\n      route: 'noop',\n      targetId: s1.existingId,\n      ...(s1.similarity !== undefined ? { similarity: s1.similarity } : {}),\n      reason: s1.reason ?? 'exact-hash-match',\n    };\n  }\n\n  const s2 = await stage2EmbeddingThreeZone.evaluate(ctx);\n  if (s2.kind === 'dedup') {\n    return {\n      route: 'noop',\n      targetId: s2.existingId,\n      ...(s2.similarity !== undefined ? { similarity: s2.similarity } : {}),\n      reason: s2.reason ?? 'embedding-zone',\n    };\n  }\n  if (s2.kind === 'admit') {\n    return { route: 'add', reason: s2.reason ?? 'embedding-cold-zone' };\n  }\n  // s2.kind === 'continue' → CONFLICT-CHECK mid-zone → spend an LLM call.\n  return { route: 'reconcile' };\n}\n\n/** A neighbour surfaced to the reconcile prompt. */\nexport interface ReconcileNeighbor {\n  readonly id: string;\n  readonly text: string;\n  readonly validFrom?: string;\n}\n\n/** Token usage for the single reconcile provider call (budget accounting). */\nexport interface ReconcileUsage {\n  readonly promptTokens: number;\n  readonly completionTokens: number;\n  readonly totalTokens: number;\n}\n\n/** Result of {@link reconcileCandidate}: the decision + its token cost. */\nexport interface ReconcileResult {\n  readonly decision: ReconcileDecision;\n  readonly usage: ReconcileUsage;\n}\n\n/** Inputs to {@link reconcileCandidate}. */\nexport interface ReconcileCandidateArgs {\n  readonly candidateText: string;\n  readonly neighbors: ReadonlyArray<ReconcileNeighbor>;\n  readonly provider: Provider;\n  readonly scope: SessionScope;\n}\n\n/**\n * System prompt for the reconcile pass. Mirrors the deep-phase judge\n * style but expands the decision space to the full ADD/UPDATE/NOOP/\n * CONFLICT loop and asks for the `targetId` of the resolved neighbour.\n *\n * @internal\n */\nexport const RECONCILE_SYSTEM_PROMPT = [\n  \"You reconcile a candidate memory against the user's existing related memories.\",\n  'Return strictly JSON: { \"action\": \"add\" | \"update\" | \"noop\" | \"conflict\", \"targetId\"?: string, \"reason\": string }.',\n  'Use \"update\" when the candidate is a newer version of an existing memory (a changed preference, location, job, or fact).',\n  'Use \"noop\" when the candidate adds nothing new (a duplicate or subset of an existing memory).',\n  'Use \"conflict\" when the candidate contradicts an existing memory and the older one should be closed.',\n  'Use \"add\" when the candidate is independent of every listed memory, or when you are unsure.',\n  'For \"update\", \"noop\", and \"conflict\", set \"targetId\" to the id of the existing memory you are resolving against.',\n].join(' ');\n\n/**\n * Run one reconcile pass. The decision is always safe to apply: parse\n * failures and dangling `targetId`s degrade to an additive write.\n *\n * @stable\n */\nexport async function reconcileCandidate(args: ReconcileCandidateArgs): Promise<ReconcileResult> {\n  const request = buildReconcileRequest(args);\n  const response = await args.provider.generate(request);\n  const usage = response.usage;\n  const promptTokens = usage.promptTokens ?? 0;\n  const completionTokens = usage.completionTokens ?? 0;\n  const totalTokens = promptTokens + completionTokens + (usage.reasoningTokens ?? 0);\n  const validIds = new Set(args.neighbors.map((n) => n.id));\n  const decision = parseReconcile(response.text, validIds);\n  return { decision, usage: { promptTokens, completionTokens, totalTokens } };\n}\n\n/**\n * Parse the reconcile model output into a {@link ReconcileDecision}.\n * Tolerates fenced blocks + trailing commentary; an unparseable body,\n * an unknown action, or a `targetId` that is not in `validTargetIds`\n * all degrade to `{ action: 'add' }` (audited via the reason).\n *\n * @internal\n */\nexport function parseReconcile(\n  text: string | undefined,\n  validTargetIds: ReadonlySet<string>,\n): ReconcileDecision {\n  const fallback: ReconcileDecision = { action: 'add', reason: 'reconcile-parse-failure' };\n  if (text === undefined || text.length === 0) return fallback;\n  const candidate = stripFence(text).trim();\n  if (candidate.length === 0) return fallback;\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(candidate);\n  } catch {\n    const slice = sliceJsonObject(candidate);\n    if (slice === null) return fallback;\n    try {\n      parsed = JSON.parse(slice);\n    } catch {\n      return fallback;\n    }\n  }\n  if (parsed === null || typeof parsed !== 'object') return fallback;\n  const obj = parsed as { action?: unknown; targetId?: unknown; reason?: unknown };\n  const reason = typeof obj.reason === 'string' && obj.reason.length > 0 ? obj.reason : undefined;\n  if (obj.action === 'add') {\n    return { action: 'add', ...(reason !== undefined ? { reason } : {}) };\n  }\n  if (obj.action === 'update' || obj.action === 'noop' || obj.action === 'conflict') {\n    const targetId = typeof obj.targetId === 'string' ? obj.targetId : null;\n    if (targetId === null || !validTargetIds.has(targetId)) {\n      // The model referenced a fact that is not one of the supplied\n      // neighbours — never rewrite an unverified id; add instead.\n      return { action: 'add', reason: 'reconcile-invalid-target' };\n    }\n    if (obj.action === 'noop') {\n      return { action: 'noop', targetId, ...(reason !== undefined ? { reason } : {}) };\n    }\n    return { action: obj.action, targetId, reason: reason ?? `reconcile-${obj.action}` };\n  }\n  return fallback;\n}\n\nfunction buildReconcileRequest(args: ReconcileCandidateArgs): ProviderRequest {\n  const neighborLines = args.neighbors\n    .map((n, i) => {\n      const vf = n.validFrom !== undefined ? ` (validFrom: ${n.validFrom})` : '';\n      return `${i + 1}. [id: ${n.id}]${vf} ${n.text}`;\n    })\n    .join('\\n');\n  const userBlock = [\n    `Candidate memory: ${args.candidateText}`,\n    '',\n    'Existing related memories:',\n    neighborLines.length > 0 ? neighborLines : '(none)',\n  ].join('\\n');\n  return {\n    messages: [{ role: 'user', content: userBlock }],\n    systemMessage: RECONCILE_SYSTEM_PROMPT,\n    temperature: 0,\n    // MCON-14: per-call output cap — the decision shape is tiny.\n    maxTokens: 256,\n    metadata: {\n      userId: args.scope.userId,\n      ...(args.scope.sessionId !== undefined ? { sessionId: args.scope.sessionId } : {}),\n      ...(args.scope.agentId !== undefined ? { agentId: args.scope.agentId } : {}),\n    },\n    outputType: { kind: 'structured' },\n  };\n}\n\n/**\n * Minimal candidate `Fact` for the pre-filter stage context. Stage 1\n * reads only `text`; Stage 2 reads only the neighbour scores — the\n * other fields are never inspected, so a synthetic id/scope is safe.\n */\nfunction synthCandidate(text: string): Fact {\n  return {\n    id: '__reconcile_candidate__',\n    kind: 'semantic',\n    userId: '__reconcile_candidate__',\n    sensitivity: 'internal',\n    text,\n    createdAt: new Date(0).toISOString(),\n  };\n}\n\nfunction stripFence(text: string): string {\n  const match = /^```[^\\n]*\\n([\\s\\S]*?)\\n```/u.exec(text.trim());\n  return match?.[1] ?? text;\n}\n\nfunction sliceJsonObject(text: string): string | null {\n  const start = text.indexOf('{');\n  const end = text.lastIndexOf('}');\n  if (start < 0 || end < start) return null;\n  return text.slice(start, end + 1);\n}\n"],"mappings":"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"}

package/dist/consolidator/runtime.d.ts

@@ -0,0 +1,62 @@
+import { ConsolidatorConfig, ConsolidatorPhase, ConsolidatorStatus, ConsolidatorTier, ConsolidatorTriggerReason, CreateConsolidatorOptions, PhaseListener, PhaseOutcome } from "./types.js";
+import { RegisterTriggersResult, SchedulerLike } from "./scheduler.js";
+import { SessionScope } from "@graphorin/core";
+
+//#region src/consolidator/runtime.d.ts
+
+/**
+ * Consolidator runtime surface returned by {@link createConsolidator}.
+ * Compatible with the placeholder shape so the facade can swap the
+ * implementation without breaking consumers.
+ *
+ * @stable
+ */
+interface Consolidator {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  trigger(reason: ConsolidatorTriggerReason, scope: SessionScope): Promise<PhaseOutcome | null>;
+  status(): Promise<ConsolidatorStatus>;
+  /**
+   * Manual trigger for the requested phase. Skips phase gating + the
+   * idle/cron scheduler so admins can flush the queue on demand.
+   */
+  fireNow(phase: ConsolidatorPhase, scope?: SessionScope): Promise<PhaseOutcome | null>;
+  /** Replace the active tier — recomputes ceilings + phase set. */
+  setTier(tier: ConsolidatorTier): Promise<void>;
+  /** Pause the consolidator until the next budget reset. */
+  pause(): Promise<void>;
+  /** Resume after `pause()`. */
+  resume(): Promise<void>;
+  /** Subscribe to phase-finished notifications. Returns an unsubscribe. */
+  onPhaseFinished(listener: PhaseListener): () => void;
+  /**
+   * Record memory-pipeline LLM spend that happened OUTSIDE a phase run
+   * (MCON-15 — e.g. workflow induction) so the daily ceilings cover it.
+   * Counted under the deep-phase bucket.
+   */
+  recordExternalSpend(tokens: number, costUsd?: number): void;
+  /** Active config — frozen snapshot. */
+  config(): ConsolidatorConfig;
+  /**
+   * Register this consolidator's cron / idle triggers with a
+   * `@graphorin/triggers` scheduler so they fire `trigger(...)`
+   * automatically (the daemon ↔ triggers bridge — MCON-4). Uses the
+   * configured `defaultScope`; throws if none was set. Turn / event
+   * triggers are skipped (consumer-emitted). The standalone server calls
+   * this in `beforeStart`.
+   */
+  registerWithScheduler(scheduler: SchedulerLike): Promise<RegisterTriggersResult>;
+  /** True when `tier === 'free'`. */
+  isFree(): boolean;
+  /** Drain DLQ rows whose `nextRetryAt` <= now. */
+  drainDlq(scope: SessionScope): Promise<number>;
+}
+/**
+ * Build the runtime consolidator.
+ *
+ * @stable
+ */
+declare function createConsolidator(opts: CreateConsolidatorOptions): Consolidator;
+//#endregion
+export { Consolidator, createConsolidator };
+//# sourceMappingURL=runtime.d.ts.map

package/dist/consolidator/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","names":[],"sources":["../../src/consolidator/runtime.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;AAsGiC,UAtChB,YAAA,CAsCgB;EAAO,KAAA,EAAA,EArC7B,OAqC6B,CAAA,IAAA,CAAA;EAQxB,IAAA,EAAA,EA5CN,OA4CM,CAAA,IAAA,CAAkB;kBA3ChB,kCAAkC,eAAe,QAAQ;YAC/D,QAAQ;;;;;iBAKH,2BAA2B,eAAe,QAAQ;;gBAEnD,mBAAmB;;WAExB;;YAEC;;4BAEgB;;;;;;;;YAQhB;;;;;;;;;mCASuB,gBAAgB,QAAQ;;;;kBAIzC,eAAe;;;;;;;iBAQjB,kBAAA,OAAyB,4BAA4B"}