memorix 1.7.3 → 1.8.0

package/src/memory/feedback.ts

@@ -0,0 +1,220 @@
+import { randomUUID } from 'node:crypto';
+import type { ObservationStatus } from '../types.js';
+import { getDatabase } from '../store/sqlite-db.js';
+export { feedbackWeightMultiplier } from './feedback-model.js';
+
+export type MemoryFeedbackSignal =
+  | 'user-correction'
+  | 'verification-success'
+  | 'verification-failure'
+  | 'code-change'
+  | 'used'
+  | 'not-used'
+  | 'code-conflict'
+  | 'strengthen'
+  | 'weaken'
+  | 'revoke';
+
+export interface MemoryFeedbackEvent {
+  signal: MemoryFeedbackSignal;
+  at: string;
+  actor?: string;
+  note?: string;
+  sourceRef?: string;
+  targetEventId?: string;
+}
+
+export interface FeedbackState {
+  weight: number;
+  status: ObservationStatus;
+  audit: MemoryFeedbackEvent[];
+}
+
+export type FeedbackCandidateKind = 'observation' | 'claim' | 'durable-memory' | 'workflow';
+
+export interface PersistedFeedbackEvent extends MemoryFeedbackEvent {
+  id: string;
+  projectId: string;
+  candidateKind: FeedbackCandidateKind;
+  candidateId: string;
+  delta: number;
+}
+
+export const FEEDBACK_DELTAS: Record<Exclude<MemoryFeedbackSignal, 'revoke'>, number> = {
+  'user-correction': -0.35,
+  'verification-success': 0.25,
+  'verification-failure': -0.25,
+  'code-change': -0.15,
+  used: 0.1,
+  'not-used': -0.05,
+  'code-conflict': -0.4,
+  strengthen: 0.2,
+  weaken: -0.2,
+};
+
+/** Deterministic feedback reducer used by MCP/CLI adapters and tests. */
+export function applyMemoryFeedback(
+  current: FeedbackState,
+  event: MemoryFeedbackEvent,
+): FeedbackState {
+  const delta = event.signal === 'revoke' ? 0 : FEEDBACK_DELTAS[event.signal];
+  const weight = Math.max(0, Math.min(2, current.weight + delta));
+  const status: ObservationStatus = (event.signal === 'code-conflict' || event.signal === 'user-correction' || event.signal === 'weaken') && weight < 0.5
+    ? 'archived'
+    : current.status;
+  return { weight, status, audit: [...current.audit, { ...event }] };
+}
+
+function rowToEvent(row: any): PersistedFeedbackEvent {
+  return {
+    id: String(row.id),
+    projectId: String(row.project_id),
+    candidateKind: row.candidate_kind,
+    candidateId: String(row.candidate_id),
+    signal: row.signal,
+    ...(row.observed_at ? { at: String(row.observed_at) } : { at: new Date().toISOString() }),
+    ...(row.actor ? { actor: String(row.actor) } : {}),
+    ...(row.note ? { note: String(row.note) } : {}),
+    ...(row.source_ref ? { sourceRef: String(row.source_ref) } : {}),
+    ...(row.target_event_id ? { targetEventId: String(row.target_event_id) } : {}),
+    delta: Number(row.delta ?? 0),
+  };
+}
+
+function candidateKey(projectId: string, candidateKind: FeedbackCandidateKind, candidateId: string): string {
+  return `${projectId}\u0000${candidateKind}\u0000${candidateId}`;
+}
+
+/**
+ * Durable feedback loop. Events are append-only; the state row is a materialized
+ * projection rebuilt from non-revoked events, so undo never destroys audit truth.
+ */
+export class MemoryFeedbackStore {
+  private db: any = null;
+
+  async init(dataDir: string): Promise<void> {
+    this.db = getDatabase(dataDir);
+  }
+
+  private requireDb(): any {
+    if (!this.db) throw new Error('MemoryFeedbackStore is not initialized.');
+    return this.db;
+  }
+
+  private loadEvents(projectId: string, candidateKind: FeedbackCandidateKind, candidateId: string): PersistedFeedbackEvent[] {
+    return this.requireDb().prepare(`
+      SELECT * FROM memory_feedback_events
+      WHERE project_id = ? AND candidate_kind = ? AND candidate_id = ?
+      ORDER BY observed_at ASC, rowid ASC
+    `).all(projectId, candidateKind, candidateId).map(rowToEvent);
+  }
+
+  private rebuild(projectId: string, candidateKind: FeedbackCandidateKind, candidateId: string): FeedbackState {
+    const events = this.loadEvents(projectId, candidateKind, candidateId);
+    const revoked = new Set(events.filter((event) => event.signal === 'revoke' && event.targetEventId).map((event) => event.targetEventId!));
+    let state: FeedbackState = { weight: 1, status: 'active', audit: [] };
+    for (const event of events) {
+      if (event.signal === 'revoke' || revoked.has(event.id)) {
+        state.audit.push(event);
+        continue;
+      }
+      state = applyMemoryFeedback(state, event);
+    }
+    this.requireDb().prepare(`
+      INSERT INTO memory_feedback_states (project_id, candidate_kind, candidate_id, weight, lifecycle_status, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_id, candidate_kind, candidate_id) DO UPDATE SET
+        weight = excluded.weight, lifecycle_status = excluded.lifecycle_status, updated_at = excluded.updated_at
+    `).run(projectId, candidateKind, candidateId, state.weight, state.status, new Date().toISOString());
+    return state;
+  }
+
+  getState(projectId: string, candidateKind: FeedbackCandidateKind, candidateId: string): FeedbackState {
+    const row = this.requireDb().prepare(`
+      SELECT weight, lifecycle_status FROM memory_feedback_states
+      WHERE project_id = ? AND candidate_kind = ? AND candidate_id = ?
+    `).get(projectId, candidateKind, candidateId);
+    if (!row) return { weight: 1, status: 'active', audit: [] };
+    return {
+      weight: Number(row.weight ?? 1),
+      status: row.lifecycle_status ?? 'active',
+      audit: this.loadEvents(projectId, candidateKind, candidateId),
+    };
+  }
+
+  listStates(projectId: string, candidateKind: FeedbackCandidateKind = 'observation'): Array<{ candidateId: string; weight: number; status: ObservationStatus; updatedAt: string }> {
+    return this.requireDb().prepare(`
+      SELECT candidate_id, weight, lifecycle_status, updated_at
+      FROM memory_feedback_states WHERE project_id = ? AND candidate_kind = ?
+      ORDER BY updated_at DESC
+    `).all(projectId, candidateKind).map((row: any) => ({
+      candidateId: String(row.candidate_id),
+      weight: Number(row.weight),
+      status: row.lifecycle_status,
+      updatedAt: String(row.updated_at),
+    }));
+  }
+
+  weights(projectId: string, candidateKind: FeedbackCandidateKind = 'observation'): Map<string, FeedbackState> {
+    const states = new Map<string, FeedbackState>();
+    for (const row of this.listStates(projectId, candidateKind)) {
+      states.set(row.candidateId, this.getState(projectId, candidateKind, row.candidateId));
+    }
+    return states;
+  }
+
+  record(input: {
+    projectId: string;
+    candidateKind: FeedbackCandidateKind;
+    candidateId: string;
+    signal: MemoryFeedbackSignal;
+    sourceRef: string;
+    actor?: string;
+    note?: string;
+    targetEventId?: string;
+    at?: string;
+  }): { event: PersistedFeedbackEvent; state: FeedbackState } {
+    if (input.signal === 'revoke' && !input.targetEventId) {
+      throw new Error('A revoke feedback event requires targetEventId.');
+    }
+    if (input.signal === 'revoke') {
+      const target = this.requireDb().prepare(`
+        SELECT 1 FROM memory_feedback_events
+        WHERE id = ? AND project_id = ? AND candidate_kind = ? AND candidate_id = ?
+      `).get(input.targetEventId, input.projectId, input.candidateKind, input.candidateId);
+      if (!target) throw new Error('The feedback event to revoke was not found in the same candidate scope.');
+    }
+    const event: PersistedFeedbackEvent = {
+      id: randomUUID(),
+      projectId: input.projectId,
+      candidateKind: input.candidateKind,
+      candidateId: input.candidateId,
+      signal: input.signal,
+      sourceRef: input.sourceRef,
+      ...(input.actor ? { actor: input.actor } : {}),
+      ...(input.note ? { note: input.note.slice(0, 2_000) } : {}),
+      ...(input.targetEventId ? { targetEventId: input.targetEventId } : {}),
+      at: input.at ?? new Date().toISOString(),
+      delta: input.signal === 'revoke' ? 0 : FEEDBACK_DELTAS[input.signal],
+    };
+    this.requireDb().prepare(`
+      INSERT INTO memory_feedback_events (
+        id, project_id, candidate_kind, candidate_id, signal, actor, note,
+        source_ref, target_event_id, delta, observed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      event.id, event.projectId, event.candidateKind, event.candidateId, event.signal,
+      event.actor ?? null, event.note ?? null, event.sourceRef, event.targetEventId ?? null,
+      event.delta, event.at,
+    );
+    return { event, state: this.rebuild(input.projectId, input.candidateKind, input.candidateId) };
+  }
+
+  audit(projectId: string, candidateKind: FeedbackCandidateKind, candidateId: string, limit = 100): PersistedFeedbackEvent[] {
+    return this.requireDb().prepare(`
+      SELECT * FROM memory_feedback_events
+      WHERE project_id = ? AND candidate_kind = ? AND candidate_id = ?
+      ORDER BY observed_at DESC, rowid DESC LIMIT ?
+    `).all(projectId, candidateKind, candidateId, Math.min(200, Math.max(1, Math.floor(limit)))).map(rowToEvent);
+  }
+}

package/src/memory/observations.ts

@@ -44,6 +44,7 @@ import { getEmbeddingProvider, isEmbeddingExplicitlyDisabled, validateEmbeddingI
 import { sanitizeCredentials } from './secret-filter.js';
 import { enqueueClaimDerivation, enqueueObservationQualification } from '../runtime/lifecycle.js';
 import { canManageObservation, resolveObservationVisibility } from './visibility.js';
+import { EvidenceCardStore } from '../store/evidence-store.js';
 
 /** In-memory observation list (loaded from persistence on init) */
 let observations: Observation[] = [];
@@ -186,6 +187,20 @@ async function bindObservationCodeRefsBestEffort(observation: Observation): Prom
   }
 }
 
+async function persistEvidenceCard(observation: Observation): Promise<void> {
+  if (!projectDir) return;
+  try {
+    const evidence = new EvidenceCardStore();
+    await evidence.init(projectDir);
+    evidence.upsertObservation(observation);
+  } catch (error) {
+    // Evidence is a derived control-plane projection. A failed projection must
+    // never roll back the canonical observation, but it must be visible for a
+    // later repair/sync pass.
+    console.error(`[memorix] Evidence card projection failed for obs-${observation.id}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 function queueClaimDerivation(observation: Observation): void {
   const dataDir = projectDir;
   const isExplicit = observation.sourceDetail === 'explicit';
@@ -692,6 +707,7 @@ export async function storeObservation(input: {
   if (!persistedCallbackInvoked) await input.onPersisted?.(observation);
 
   await bindObservationCodeRefsBestEffort(observation);
+  await persistEvidenceCard(observation);
   queueObservationQualification(observation);
   if (resolveObservationVisibility(observation) === 'project') {
     queueClaimDerivation(observation);
@@ -828,6 +844,7 @@ async function upsertObservation(
   }
 
   await bindObservationCodeRefsBestEffort(existing);
+  await persistEvidenceCard(existing);
   queueObservationQualification(existing);
   if (resolveObservationVisibility(existing) === 'project') {
     queueClaimDerivation(existing);
@@ -1002,6 +1019,8 @@ export async function resolveObservations(
     });
   }
 
+  for (const observation of changed) await persistEvidenceCard(observation);
+
   return { resolved, notFound };
 }
 

package/src/memory/retention.ts

@@ -15,9 +15,10 @@
  * retention period but are no longer permanently immune — they decay normally.
  */
 
-import type { MemorixDocument, Observation, ObservationReader } from '../types.js';
+import type { MemorixDocument, Observation, ObservationReader, ObservationStatus } from '../types.js';
 import { getObservationStore } from '../store/obs-store.js';
 import { canManageObservation } from './visibility.js';
+import { feedbackWeightMultiplier } from './feedback-model.js';
 
 // ── Importance → Retention Period mapping ────────────────────────────
 
@@ -113,6 +114,7 @@ export function getEffectiveRetentionDays(doc: MemorixDocument): number {
 export function isImmune(doc: MemorixDocument): boolean {
   // Probe observations are operational heartbeats -- never immune, regardless of valueCategory or access.
   if (doc.type === 'probe') return false;
+  if (doc.feedbackStatus === 'archived') return false;
 
   // A candidate has not earned durable status. Never let an automatic core
   // classification turn unqualified capture into permanently retained memory.
@@ -164,6 +166,7 @@ export interface RelevanceScore {
   accessBoost: number;
   ageDays: number;
   isImmune: boolean;
+  feedbackMultiplier: number;
 }
 
 /**
@@ -202,7 +205,12 @@ export function calculateRelevance(
   const accessCount = doc.accessCount ?? 0;
   const accessBoost = Math.min(2.0, 1 + 0.1 * accessCount);
 
-  let totalScore = base * decayFactor * accessBoost;
+  // Legacy memories have no feedback row. Preserve their historical score
+  // exactly; only an explicit feedback projection changes relevance.
+  const feedbackMultiplier = doc.feedbackWeight === undefined
+    ? 1
+    : feedbackWeightMultiplier(doc.feedbackWeight);
+  let totalScore = base * decayFactor * accessBoost * feedbackMultiplier;
 
   // Immune observations get minimum 0.5 relevance
   const immune = isImmune(doc);
@@ -218,6 +226,7 @@ export function calculateRelevance(
     accessBoost,
     ageDays,
     isImmune: immune,
+    feedbackMultiplier,
   };
 }
 
@@ -248,6 +257,7 @@ export type RetentionZone = 'active' | 'stale' | 'archive-candidate';
  */
 export function getRetentionZone(doc: MemorixDocument, referenceTime?: Date): RetentionZone {
   const now = referenceTime ?? new Date();
+  if (doc.feedbackStatus === 'archived') return 'archive-candidate';
   const importance = getImportanceLevel(doc);
   const retention = getEffectiveRetentionDays(doc);
 
@@ -344,6 +354,7 @@ export interface RetentionProjection extends RetentionExplanation {
 export interface ObservationRetentionProjectionOptions {
   referenceTime?: Date;
   accessMap?: ObservationAccessMap;
+  feedback?: { weight: number; status: ObservationStatus };
 }
 
 export interface RetentionProjectionSummary {
@@ -415,6 +426,7 @@ export function explainRetention(
 export function toRetentionDocument(
   obs: Observation,
   accessMap?: ObservationAccessMap,
+  feedback?: { weight: number; status: ObservationStatus },
 ): MemorixDocument {
   const access = accessMap?.get(obs.id);
   return {
@@ -438,6 +450,7 @@ export function toRetentionDocument(
     valueCategory: obs.valueCategory ?? '',
     admissionState: obs.admissionState ?? '',
     admissionReason: obs.admissionReason ?? '',
+    ...(feedback ? { feedbackWeight: feedback.weight, feedbackStatus: feedback.status } : {}),
   };
 }
 
@@ -446,7 +459,7 @@ export function projectObservationRetention(
   observation: Observation,
   options: ObservationRetentionProjectionOptions = {},
 ): RetentionProjection {
-  const document = toRetentionDocument(observation, options.accessMap);
+  const document = toRetentionDocument(observation, options.accessMap, options.feedback);
   const relevance = calculateRelevance(document, options.referenceTime);
   const explanation = explainRetention(document, options.referenceTime);
 
@@ -497,12 +510,25 @@ export interface ArchiveExpiredBatchResult {
   nextCursor?: number;
 }
 
+async function loadFeedbackStore(dataDir: string): Promise<import('./feedback.js').MemoryFeedbackStore | undefined> {
+  try {
+    const { MemoryFeedbackStore } = await import('./feedback.js');
+    const store = new MemoryFeedbackStore();
+    await store.init(dataDir);
+    return store;
+  } catch {
+    // Pre-1.8 databases or degraded SQLite installations keep the legacy
+    // retention behavior until the feedback projection is available.
+    return undefined;
+  }
+}
+
 /**
  * Archive one bounded page of a project's active memories. The caller owns the
  * cursor, which makes the operation safe to run from a durable maintenance job.
  */
 export async function archiveExpiredBatch(
-  _projectDir: string,
+  projectDir: string,
   options: ArchiveExpiredBatchOptions,
 ): Promise<ArchiveExpiredBatchResult> {
   const store = getObservationStore();
@@ -513,6 +539,7 @@ export async function archiveExpiredBatch(
     afterId,
     limit: limit + 1,
   });
+  const feedback = await loadFeedbackStore(projectDir);
   const hasMore = page.length > limit;
   const scanned = hasMore ? page.slice(0, limit) : page;
   const candidateIds = scanned
@@ -520,6 +547,7 @@ export async function archiveExpiredBatch(
     .filter((observation) => projectObservationRetention(observation, {
       accessMap: options.accessMap,
       referenceTime: options.referenceTime,
+      ...(feedback ? { feedback: feedback.getState(options.projectId, 'observation', String(observation.id)) } : {}),
     }).zone === 'archive-candidate')
     .map((observation) => observation.id);
 
@@ -580,6 +608,7 @@ export async function archiveExpired(
     return { archived, remaining };
   }
 
+  const feedback = await loadFeedbackStore(projectDir);
   return await store.atomic(async (tx) => {
     const allObs = await tx.loadAll();
 
@@ -591,7 +620,11 @@ export async function archiveExpired(
     const archivedIds: number[] = [];
 
     for (const obs of activeObs) {
-      const retention = projectObservationRetention(obs, { accessMap, referenceTime });
+      const retention = projectObservationRetention(obs, {
+        accessMap,
+        referenceTime,
+        ...(feedback ? { feedback: feedback.getState(obs.projectId, 'observation', String(obs.id)) } : {}),
+      });
       if (retention.zone === 'archive-candidate') {
         archivedIds.push(obs.id);
       }

package/src/server/mcp-binding-store.ts

@@ -0,0 +1,79 @@
+import { randomUUID } from 'node:crypto';
+import { getDatabase } from '../store/sqlite-db.js';
+
+export interface McpProjectBinding {
+  handleId: string;
+  projectId: string;
+  projectRoot: string;
+  dataDir: string;
+  createdAt: string;
+  lastUsedAt: string;
+  expiresAt?: string;
+}
+
+function rowToBinding(row: any): McpProjectBinding {
+  return {
+    handleId: String(row.handle_id),
+    projectId: String(row.project_id),
+    projectRoot: String(row.project_root),
+    dataDir: String(row.data_dir),
+    createdAt: String(row.created_at),
+    lastUsedAt: String(row.last_used_at),
+    ...(row.expires_at ? { expiresAt: String(row.expires_at) } : {}),
+  };
+}
+
+/** Durable project binding handles for stateless MCP requests. */
+export class McpBindingStore {
+  private db: any = null;
+
+  async init(dataDir: string): Promise<void> {
+    this.db = getDatabase(dataDir);
+  }
+
+  private requireDb(): any {
+    if (!this.db) throw new Error('McpBindingStore is not initialized.');
+    return this.db;
+  }
+
+  create(input: { projectId: string; projectRoot: string; dataDir: string; ttlMs?: number }): McpProjectBinding {
+    const now = new Date();
+    const binding: McpProjectBinding = {
+      handleId: `mxh_${randomUUID().replace(/-/g, '')}`,
+      projectId: input.projectId,
+      projectRoot: input.projectRoot,
+      dataDir: input.dataDir,
+      createdAt: now.toISOString(),
+      lastUsedAt: now.toISOString(),
+      ...(input.ttlMs && input.ttlMs > 0 ? { expiresAt: new Date(now.getTime() + input.ttlMs).toISOString() } : {}),
+    };
+    this.requireDb().prepare(`
+      INSERT INTO mcp_bindings (handle_id, project_id, project_root, data_dir, created_at, last_used_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(binding.handleId, binding.projectId, binding.projectRoot, binding.dataDir, binding.createdAt, binding.lastUsedAt, binding.expiresAt ?? null);
+    return binding;
+  }
+
+  get(handleId: string): McpProjectBinding | undefined {
+    const row = this.requireDb().prepare(`SELECT * FROM mcp_bindings WHERE handle_id = ?`).get(handleId);
+    if (!row) return undefined;
+    const binding = rowToBinding(row);
+    if (binding.expiresAt && Date.parse(binding.expiresAt) <= Date.now()) {
+      this.delete(handleId);
+      return undefined;
+    }
+    return binding;
+  }
+
+  touch(handleId: string): McpProjectBinding | undefined {
+    const binding = this.get(handleId);
+    if (!binding) return undefined;
+    const lastUsedAt = new Date().toISOString();
+    this.requireDb().prepare(`UPDATE mcp_bindings SET last_used_at = ? WHERE handle_id = ?`).run(lastUsedAt, handleId);
+    return { ...binding, lastUsedAt };
+  }
+
+  delete(handleId: string): void {
+    this.requireDb().prepare(`DELETE FROM mcp_bindings WHERE handle_id = ?`).run(handleId);
+  }
+}

package/src/server/mcp-diagnostics.ts

@@ -0,0 +1,40 @@
+/** MCP compatibility diagnostics shared by HTTP and CLI-facing checks. */
+
+export const CURRENT_MCP_PROTOCOL_VERSION = '2026-07-28';
+export const LEGACY_MCP_PROTOCOL_VERSION = '2024-11-05';
+export const MCP_SERVER_NAME = 'io.github.AVIDS2/memorix';
+
+export interface McpDiagnostics {
+  serverName: string;
+  protocol: {
+    current: string;
+    legacy: string;
+    statelessRequests: 'supported' | 'compatibility-only' | 'unsupported';
+    statefulStreamableHttp: 'supported';
+  };
+  capabilities: {
+    tasks: 'supported' | 'unsupported';
+    polling: 'supported' | 'unsupported';
+    listCache: 'supported';
+    explicitProjectHandle: 'supported';
+  };
+}
+
+/** The pinned SDK is stateful; do not present a fake durable task loop. */
+export function getMcpDiagnostics(): McpDiagnostics {
+  return {
+    serverName: MCP_SERVER_NAME,
+    protocol: {
+      current: CURRENT_MCP_PROTOCOL_VERSION,
+      legacy: LEGACY_MCP_PROTOCOL_VERSION,
+    statelessRequests: 'supported',
+      statefulStreamableHttp: 'supported',
+    },
+    capabilities: {
+      tasks: 'unsupported',
+      polling: 'unsupported',
+      listCache: 'supported',
+      explicitProjectHandle: 'supported',
+    },
+  };
+}

package/src/server/tool-profile.ts

@@ -40,6 +40,10 @@ export const TOOL_PROFILES: Record<string, ReadonlyArray<ToolProfile>> = Object.
   // multimodal support to one additional schema rather than enabling lite.
   memorix_session_start:      ['micro', 'lite', 'team', 'full'],
   memorix_media:              ['micro', 'lite', 'team', 'full'],
+  // Evidence and feedback are deliberate operator/context-control surfaces;
+  // keep the default micro profile at its nine-tool token budget.
+  memorix_evidence:           ['lite', 'team', 'full'],
+  memorix_feedback:           ['lite', 'team', 'full'],
 
   // ── lite: extended solo memory surface ────────────────────────────
   memorix_graph_context:      ['lite', 'team', 'full'],