memorix 1.2.1 → 1.2.3

package/src/orchestrate/memorix-bridge.ts

@@ -90,6 +90,14 @@ async function getSearchObservations() {
   return _searchObservations;
 }
 
+function automaticActorId(...parts: string[]): string {
+  return `orchestrator:${createHash('sha256').update(parts.join('\u0000')).digest('hex').slice(0, 24)}`;
+}
+
+function isEligibleAutomaticLesson(entry: { admissionState?: string }): boolean {
+  return entry.admissionState !== 'candidate' && entry.admissionState !== 'ephemeral';
+}
+
 // ── 5a. Fix Loop Memory (CORE — always on) ────────────────────────
 
 /**
@@ -104,6 +112,7 @@ export function storeVerifiedFix(fix: FixResult): void {
 
   const errorHash = hashErrorPattern(fix.errorOutput);
   const confidence = fix.fixAttempt === 1 ? 'high' : fix.fixAttempt === 2 ? 'medium' : 'low';
+  const createdByAgentId = automaticActorId(fix.projectId, 'verified-fix', fix.gate, errorHash);
 
   // Fire-and-forget — catches all errors silently
   void (async () => {
@@ -126,6 +135,11 @@ export function storeVerifiedFix(fix: FixResult): void {
         source: 'agent',
         sourceDetail: 'hook',
         valueCategory: confidence === 'high' ? 'core' : 'contextual',
+        admissionState: 'candidate',
+        admissionReason: 'verified orchestration fix awaits current Code Memory qualification',
+        visibility: 'personal',
+        createdByAgentId,
+        visibilityReader: { projectId: fix.projectId, agentId: createdByAgentId },
       });
     } catch { /* fire-and-forget */ }
   })();
@@ -138,6 +152,7 @@ export function storeVerifiedFix(fix: FixResult): void {
  */
 export function storeFixExhausted(fix: FixResult): void {
   const errorHash = hashErrorPattern(fix.errorOutput);
+  const createdByAgentId = automaticActorId(fix.projectId, 'fix-exhausted', fix.gate, errorHash);
 
   void (async () => {
     try {
@@ -158,6 +173,11 @@ export function storeFixExhausted(fix: FixResult): void {
         source: 'agent',
         sourceDetail: 'hook',
         valueCategory: 'contextual',
+        admissionState: 'candidate',
+        admissionReason: 'automatic orchestration failure awaits current Code Memory qualification',
+        visibility: 'personal',
+        createdByAgentId,
+        visibilityReader: { projectId: fix.projectId, agentId: createdByAgentId },
       });
     } catch { /* fire-and-forget */ }
   })();
@@ -182,6 +202,7 @@ export async function searchKnownFixes(
       search({
         query: searchQuery,
         projectId,
+        reader: { projectId },
         type: 'problem-solution',
         limit: 3,
         status: 'active',
@@ -190,6 +211,7 @@ export async function searchKnownFixes(
     ]);
 
     return (results as any[])
+      .filter(isEligibleAutomaticLesson)
       .filter((r: any) => (r.score ?? 1) > 0.3) // Only reasonably relevant
       .map((r: any) => ({
         id: r.id ?? 0,
@@ -226,6 +248,7 @@ export async function searchLessons(
       search({
         query,
         projectId,
+        reader: { projectId },
         limit: config.maxLessons + 2, // Fetch extra for filtering
         status: 'active',
       }),
@@ -233,6 +256,7 @@ export async function searchLessons(
     ]);
 
     const lessons = (results as any[])
+      .filter(isEligibleAutomaticLesson)
       .filter((r: any) =>
         (r.type === 'problem-solution' || r.type === 'gotcha') &&
         (r.score ?? 1) > 0.5, // Only high-relevance (Safeguard 5: project isolation already handled by projectId filter)
@@ -282,6 +306,8 @@ export function storeTaskCompletion(opts: {
   durationMs: number;
   tailOutput: string;
 }): void {
+  const createdByAgentId = automaticActorId(opts.projectId, opts.pipelineId, opts.taskId, opts.agentName);
+
   void (async () => {
     try {
       const store = await getStoreObservation();
@@ -300,6 +326,11 @@ export function storeTaskCompletion(opts: {
         source: 'agent',
         sourceDetail: 'hook',
         valueCategory: 'ephemeral',
+        admissionState: 'ephemeral',
+        admissionReason: 'pipeline completion retained only as a short-lived trace',
+        visibility: 'personal',
+        createdByAgentId,
+        visibilityReader: { projectId: opts.projectId, agentId: createdByAgentId },
       });
     } catch { /* fire-and-forget */ }
   })();
@@ -318,6 +349,8 @@ export function storePipelineSummary(opts: {
   failed: number;
   elapsedMs: number;
 }): void {
+  const createdByAgentId = automaticActorId(opts.projectId, opts.pipelineId, 'summary');
+
   void (async () => {
     try {
       const store = await getStoreObservation();
@@ -338,6 +371,11 @@ export function storePipelineSummary(opts: {
         source: 'agent',
         sourceDetail: 'hook',
         valueCategory: 'contextual',
+        admissionState: 'candidate',
+        admissionReason: 'automatic pipeline summary awaits current Code Memory qualification',
+        visibility: 'personal',
+        createdByAgentId,
+        visibilityReader: { projectId: opts.projectId, agentId: createdByAgentId },
       });
     } catch { /* fire-and-forget */ }
   })();

package/src/runtime/control-plane-maintenance.ts

@@ -11,6 +11,7 @@ export const CONTROL_PLANE_MAINTENANCE_KINDS: readonly MaintenanceJobKind[] = [
   'retention-archive',
   'consolidation',
   'codegraph-refresh',
+  'observation-qualify',
   'claim-derive',
   'claim-requalification',
   'knowledge-compile',

package/src/runtime/isolated-maintenance.ts

@@ -12,6 +12,7 @@ export const ISOLATED_MAINTENANCE_JOB_KINDS: readonly MaintenanceJobKind[] = [
   'retention-archive',
   'consolidation',
   'codegraph-refresh',
+  'observation-qualify',
   'claim-derive',
   'claim-requalification',
   'knowledge-compile',

package/src/runtime/lifecycle.ts

@@ -65,6 +65,24 @@ export function enqueueClaimDerivation(input: {
   });
 }
 
+/**
+ * Automatic captures are initially only candidates. Qualification runs in the
+ * durable maintenance lane after Code Memory has a chance to refresh.
+ */
+export function enqueueObservationQualification(input: {
+  dataDir: string;
+  projectId: string;
+  source: string;
+  queue?: MaintenanceQueue;
+}): void {
+  queueFor(input).enqueue({
+    projectId: input.projectId,
+    kind: 'observation-qualify',
+    dedupeKey: 'observation-qualify',
+    payload: { source: input.source, limit: 100 },
+  });
+}
+
 /**
  * The follow-up jobs operate on the same workspace the Workset reads: a
  * versioned workspace when present, otherwise the local workspace.

package/src/runtime/maintenance-jobs.ts

@@ -8,6 +8,7 @@ export const MAINTENANCE_JOB_KINDS = [
   'retention-archive',
   'consolidation',
   'codegraph-refresh',
+  'observation-qualify',
   'claim-derive',
   'claim-requalification',
   'knowledge-compile',

package/src/runtime/maintenance-runner.ts

@@ -3,6 +3,7 @@ import { loadDotenv } from '../config/dotenv-loader.js';
 import { initProjectRoot } from '../config/yaml-loader.js';
 import { initLLM } from '../llm/provider.js';
 import { initObservationStore } from '../store/obs-store.js';
+import { initObservations } from '../memory/observations.js';
 import {
   MAINTENANCE_JOB_KINDS,
   type MaintenanceJob,
@@ -58,6 +59,7 @@ export async function executeMaintenanceRequest(
   initProjectRoot(request.projectRoot);
   loadDotenv(request.projectRoot);
   await initObservationStore(request.dataDir);
+  await initObservations(request.dataDir);
   if (request.job.kind === 'consolidation') initLLM();
 
   const handler = createProjectMaintenanceHandler(

package/src/runtime/project-maintenance.ts

@@ -6,6 +6,7 @@ import { runMaintenanceInChildProcess } from './isolated-maintenance.js';
 import {
   enqueueClaimRequalification,
   enqueueKnowledgeFollowups,
+  enqueueObservationQualification,
   type MaintenanceQueue,
 } from './lifecycle.js';
 
@@ -14,6 +15,7 @@ const DEFAULT_RETENTION_BATCH_SIZE = 100;
 const DEFAULT_CONSOLIDATION_BATCH_SIZE = 200;
 const DEFAULT_CODEGRAPH_MAX_FILES = 5_000;
 const DEFAULT_CLAIM_DERIVATION_BATCH_SIZE = 100;
+const DEFAULT_OBSERVATION_QUALIFICATION_BATCH_SIZE = 100;
 const VECTOR_RETRY_DELAY_MS = 5_000;
 const DEDUP_PER_PAIR_TIMEOUT_MS = 5_000;
 
@@ -68,6 +70,19 @@ function claimDerivationCursor(payload: Record<string, unknown>): number {
     : 0;
 }
 
+function observationQualificationBatchSize(payload: Record<string, unknown>): number {
+  const value = payload.limit;
+  if (typeof value !== 'number' || !Number.isFinite(value)) return DEFAULT_OBSERVATION_QUALIFICATION_BATCH_SIZE;
+  return Math.min(500, Math.max(1, Math.floor(value)));
+}
+
+function observationQualificationCursor(payload: Record<string, unknown>): number {
+  const value = payload.cursor;
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.max(0, Math.floor(value))
+    : 0;
+}
+
 function observationId(payload: Record<string, unknown>): number | undefined {
   const value = payload.observationId;
   return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
@@ -275,6 +290,80 @@ export function createProjectMaintenanceHandler(
         ...(snapshot?.id ? { snapshotId: snapshot.id } : {}),
         ...(options.maintenanceQueue ? { queue: options.maintenanceQueue } : {}),
       });
+      enqueueObservationQualification({
+        projectId,
+        dataDir: projectDir,
+        source: 'codegraph-refresh',
+        ...(options.maintenanceQueue ? { queue: options.maintenanceQueue } : {}),
+      });
+      return { action: 'complete' };
+    }
+
+    if (job.kind === 'observation-qualify') {
+      const [
+        { CodeGraphStore },
+        { bindObservationToCode },
+        { getObservationStore },
+        { qualifyCandidateFromCurrentCode },
+        { updateObservationAdmission },
+      ] = await Promise.all([
+        import('../codegraph/store.js'),
+        import('../codegraph/binder.js'),
+        import('../store/obs-store.js'),
+        import('../memory/admission.js'),
+        import('../memory/observations.js'),
+      ]);
+      const codeStore = new CodeGraphStore();
+      await codeStore.init(projectDir);
+      const limit = observationQualificationBatchSize(job.payload);
+      const page = await getObservationStore().loadByProject(projectId, {
+        status: 'active',
+        afterId: observationQualificationCursor(job.payload),
+        limit: limit + 1,
+      });
+      const hasMore = page.length > limit;
+      const observations = hasMore ? page.slice(0, limit) : page;
+      const indexedAtMs = Date.parse(codeStore.status(projectId).indexedAt ?? '');
+
+      for (const observation of observations) {
+        if (observation.admissionState !== 'candidate') continue;
+        // A candidate may only earn delivery after a Code Memory scan that
+        // happened at or after it was captured. A stale snapshot is evidence
+        // about an earlier project state, not a reason to inject this record.
+        if (!Number.isFinite(indexedAtMs) || indexedAtMs < Date.parse(observation.createdAt)) continue;
+        await bindObservationToCode(codeStore, observation);
+        const currentCodeReferenceCount = codeStore
+          .listObservationRefs(projectId, observation.id)
+          .filter((reference) => reference.status === 'current')
+          .length;
+        const qualification = qualifyCandidateFromCurrentCode({
+          observation,
+          currentCodeReferenceCount,
+        });
+        if (!qualification) continue;
+        await updateObservationAdmission({
+          observationId: observation.id,
+          projectId,
+          expectedState: 'candidate',
+          // Automatic capture earns project visibility only after a current
+          // Code Memory link exists. Explicit/private records retain scope.
+          ...(observation.sourceDetail === 'hook' ? { visibility: 'project' as const } : {}),
+          ...qualification,
+        });
+      }
+
+      if (hasMore && observations.length > 0) {
+        return {
+          action: 'reschedule',
+          delayMs: 0,
+          resetAttempts: true,
+          payload: {
+            ...job.payload,
+            cursor: observations[observations.length - 1].id,
+            limit,
+          },
+        };
+      }
       return { action: 'complete' };
     }
 

package/src/sdk.ts

@@ -25,7 +25,13 @@ import type {
   ProgressInfo,
   ProjectInfo,
   DetectionResult,
+  ObservationReader,
 } from './types.js';
+import {
+  canManageObservation,
+  canReadObservation,
+  filterReadableObservations,
+} from './memory/visibility.js';
 
 // ── Re-exports for convenience ──────────────────────────────────────
 
@@ -97,12 +103,17 @@ export interface ResolveResult {
  * Memorix observations without MCP overhead.
  *
  * Each client initializes its own SQLite backend and Orama search index,
- * scoped to a single project. Call `close()` when done to release resources.
+ * scoped to a single project. It is an unbound project reader by default, so
+ * it exposes only project-shared records and cannot alter personal or team
+ * records. Use an identity-bound MCP session for private coordination data.
+ * Call `close()` when done to release resources.
  */
 export class MemoryClient {
   private _projectId: string;
   private _projectRoot: string;
   private _dataDir: string;
+  /** SDK calls are unbound by default, so they see only project-shared records. */
+  private _reader: ObservationReader;
   private _closed = false;
 
   // Internal module references — loaded lazily to avoid top-level side effects
@@ -116,6 +127,7 @@ export class MemoryClient {
     this._projectId = projectId;
     this._projectRoot = projectRoot;
     this._dataDir = dataDir;
+    this._reader = { projectId };
   }
 
   /** The canonical project ID (derived from Git remote or local path) */
@@ -182,6 +194,7 @@ export class MemoryClient {
     return this._observations.storeObservation({
       ...input,
       projectId: this._projectId,
+      visibilityReader: this._reader,
     });
   }
 
@@ -207,6 +220,7 @@ export class MemoryClient {
       type: options.type,
       source: options.source,
       status: options.status === 'all' ? undefined : (options.status ?? 'active'),
+      reader: this._reader,
     };
 
     return this._oramaStore.searchObservations(searchOpts);
@@ -218,7 +232,8 @@ export class MemoryClient {
   async get(id: number): Promise<Observation | undefined> {
     this._ensureOpen();
     await this._freshness.withFreshIndex(() => {});
-    return this._observations.getObservation(id, this._projectId);
+    const observation = this._observations.getObservation(id, this._projectId);
+    return observation && canReadObservation(observation, this._reader) ? observation : undefined;
   }
 
   /**
@@ -227,7 +242,10 @@ export class MemoryClient {
   async getAll(): Promise<Observation[]> {
     this._ensureOpen();
     await this._freshness.withFreshIndex(() => {});
-    return this._observations.getProjectObservations(this._projectId);
+    return filterReadableObservations(
+      this._observations.getProjectObservations(this._projectId),
+      this._reader,
+    );
   }
 
   /**
@@ -236,7 +254,10 @@ export class MemoryClient {
   async count(): Promise<number> {
     this._ensureOpen();
     await this._freshness.withFreshIndex(() => {});
-    return this._observations.getProjectObservations(this._projectId).length;
+    return filterReadableObservations(
+      this._observations.getProjectObservations(this._projectId),
+      this._reader,
+    ).length;
   }
 
   /**
@@ -253,7 +274,16 @@ export class MemoryClient {
    */
   async resolve(ids: number[], status: ObservationStatus = 'resolved'): Promise<ResolveResult> {
     this._ensureOpen();
-    return this._observations.resolveObservations(ids, status);
+    const manageableIds = ids.filter((id) => {
+      const observation = this._observations.getObservation(id, this._projectId);
+      return observation && canManageObservation(observation, this._reader);
+    });
+    const deniedIds = ids.filter((id) => !manageableIds.includes(id));
+    const result = await this._observations.resolveObservations(manageableIds, status);
+    return {
+      resolved: result.resolved,
+      notFound: [...new Set([...result.notFound, ...deniedIds])],
+    };
   }
 
   /**