memorix 1.2.1 → 1.2.3

package/src/store/orama-store.ts

@@ -9,9 +9,10 @@
  */
 
 import { create, insert, search, remove, update, count, getByID, type AnyOrama } from '@orama/orama';
-import type { MemorixDocument, SearchOptions, IndexEntry, KnowledgeLayer } from '../types.js';
+import type { MemorixDocument, SearchOptions, IndexEntry, KnowledgeLayer, ObservationReader } from '../types.js';
 import { OBSERVATION_ICONS, type ObservationType } from '../types.js';
 import { resolveKnowledgeLayer } from '../skills/mini-skills.js';
+import { canReadObservation } from '../memory/visibility.js';
 import { getEmbeddingProvider, type EmbeddingProvider } from '../embedding/provider.js';
 import { calculateProjectAffinity, extractProjectKeywords, type AffinityContext, type MemoryContent } from './project-affinity.js';
 import { detectQueryIntent, applyIntentBoost } from '../search/intent-detector.js';
@@ -175,6 +176,11 @@ async function initializeDb(
     source: 'string' as const,
     sourceDetail: 'string' as const,
     valueCategory: 'string' as const,
+    admissionState: 'string' as const,
+    admissionReason: 'string' as const,
+    visibility: 'string' as const,
+    createdByAgentId: 'string' as const,
+    sharedWithAgentIds: 'string' as const,
     documentType: 'string' as const,
     knowledgeLayer: 'string' as const,
   };
@@ -390,6 +396,13 @@ export async function hydrateIndex(
         lastAccessedAt: obs.lastAccessedAt || '',
         status: obs.status ?? 'active',
         source: obs.source || 'agent',
+        sourceDetail: obs.sourceDetail ?? '',
+        valueCategory: obs.valueCategory ?? '',
+        admissionState: obs.admissionState ?? '',
+        admissionReason: obs.admissionReason ?? '',
+        visibility: obs.visibility ?? 'project',
+        createdByAgentId: obs.createdByAgentId ?? '',
+        sharedWithAgentIds: JSON.stringify(obs.sharedWithAgentIds ?? []),
         documentType: 'observation',
         knowledgeLayer: resolveKnowledgeLayer('observation', obs.sourceDetail, obs.source),
         ...(compatibleVector ? { embedding: compatibleVector } : {}),
@@ -443,6 +456,26 @@ export async function insertObservation(doc: MemorixDocument): Promise<void> {
   rememberObservationDoc(doc);
 }
 
+/**
+ * Update retrieval metadata without rebuilding an embedding. Admission is
+ * deliberately metadata-only: promotion must not create another embedding
+ * request or delay a background qualification job.
+ */
+export async function updateObservationMetadata(
+  projectId: string,
+  observationId: number,
+  patch: Partial<Pick<MemorixDocument, 'admissionState' | 'admissionReason' | 'visibility' | 'createdByAgentId' | 'sharedWithAgentIds'>>,
+): Promise<boolean> {
+  const database = await getDb();
+  const id = makeOramaObservationId(projectId, observationId);
+  const existing = getByID(database, id) as MemorixDocument | undefined;
+  if (!existing) return false;
+  const next = { ...existing, ...patch };
+  await update(database, id, next);
+  rememberObservationDoc(next);
+  return true;
+}
+
 /**
  * Remove an observation document by its Orama internal ID.
  */
@@ -643,6 +676,9 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
       const doc = hit.document as unknown as MemorixDocument;
       return projectIds.includes(doc.projectId);
     })
+    // Visibility is enforced before scoring/ranking so private records cannot
+    // affect result order, fallback behavior, or downstream detail reads.
+    .filter((hit) => canReadObservation(hit.document as unknown as MemorixDocument, options.reader))
     // Post-filter by status (active/resolved/archived)
     .filter((hit) => {
       if (statusFilter === 'all') return true;
@@ -682,6 +718,8 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
         source: (doc.source || 'agent') as 'agent' | 'git' | 'manual',
         sourceDetail: (doc.sourceDetail || undefined) as 'explicit' | 'hook' | 'git-ingest' | undefined,
         valueCategory: (doc.valueCategory || undefined) as 'core' | 'contextual' | 'ephemeral' | undefined,
+        admissionState: (doc.admissionState || undefined) as IndexEntry['admissionState'],
+        visibility: (doc.visibility || undefined) as IndexEntry['visibility'],
         entityName: doc.entityName || undefined,
         documentType: (doc.documentType || 'observation') as 'observation' | 'mini-skill',
         knowledgeLayer: (doc.knowledgeLayer || 'project-truth') as KnowledgeLayer,
@@ -752,6 +790,16 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
     }));
   }
 
+  // Automatic capture is useful as an audit trail, but unqualified evidence
+  // should not crowd out durable project knowledge in ordinary retrieval.
+  // Keep it available as a fallback when it is all the project has.
+  if (hasQuery) {
+    const qualifiedEntries = intermediate.filter(
+      (entry) => entry.admissionState !== 'candidate' && entry.admissionState !== 'ephemeral',
+    );
+    if (qualifiedEntries.length > 0) intermediate = qualifiedEntries;
+  }
+
   // Re-sort: chronological for WHEN queries, relevance for others
   if (intentResult?.preferChronological) {
     intermediate.sort((a, b) => new Date(b.rawTime).getTime() - new Date(a.rawTime).getTime());
@@ -960,7 +1008,8 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
   let entries: IndexEntry[] = intermediate.map(({ rawTime: _, _isCommandLog: _c, ...rest }: any) => rest);
 
   for (const hit of results.hits) {
-    rememberObservationDoc(hit.document as unknown as MemorixDocument);
+    const doc = hit.document as unknown as MemorixDocument;
+    if (canReadObservation(doc, options.reader)) rememberObservationDoc(doc);
   }
 
   // Explainable recall: annotate entries with match reasons (O(1) lookup via Map)
@@ -1013,7 +1062,10 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
 
   // Record access for returned results (fire-and-forget, non-blocking).
   if (options.trackAccess !== false) {
-    const hitDocs = results.hits.map((h) => ({ id: h.id, doc: h.document as unknown as MemorixDocument }));
+    const returnedKeys = new Set(entries.map((entry) => makeEntryKey(entry.projectId, entry.id)));
+    const hitDocs = results.hits
+      .map((hit) => ({ id: hit.id, doc: hit.document as unknown as MemorixDocument }))
+      .filter(({ doc }) => returnedKeys.has(makeEntryKey(doc.projectId, doc.observationId)));
     recordAccessBatch(hitDocs).catch(() => {});
   }
 
@@ -1071,6 +1123,7 @@ export async function getTimeline(
   projectId?: string,
   depthBefore = 3,
   depthAfter = 3,
+  reader?: ObservationReader,
 ): Promise<{ before: IndexEntry[]; anchor: IndexEntry | null; after: IndexEntry[] }> {
   // Use in-memory observations for reliable lookup
   // (Orama search with empty term is unreliable — same fix as compactDetail)
@@ -1079,9 +1132,9 @@ export async function getTimeline(
   const rawObs = await withFreshIndex(() => getAllObservations());
 
   // Filter by project if specified — prevents cross-project context leaking
-  const allObs = projectId
+  const allObs = (projectId
     ? rawObs.filter((o) => o.projectId === projectId)
-    : rawObs;
+    : rawObs).filter((observation) => canReadObservation(observation, reader));
 
   // Sort by creation time
   const sorted = allObs.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
@@ -1093,7 +1146,7 @@ export async function getTimeline(
 
   const toIndexEntry = (obs: {
     id: number; type: string; title: string; tokens: number; createdAt: string;
-    source?: string; sourceDetail?: string; valueCategory?: string;
+    source?: string; sourceDetail?: string; valueCategory?: string; admissionState?: string; visibility?: string;
   }): IndexEntry => {
     const obsType = obs.type as ObservationType;
     return {
@@ -1106,6 +1159,8 @@ export async function getTimeline(
       source: (obs.source as IndexEntry['source']) || undefined,
       sourceDetail: (obs.sourceDetail as IndexEntry['sourceDetail']) || undefined,
       valueCategory: (obs.valueCategory as IndexEntry['valueCategory']) || undefined,
+      admissionState: (obs.admissionState as IndexEntry['admissionState']) || undefined,
+      visibility: (obs.visibility as IndexEntry['visibility']) || undefined,
     };
   };
 

package/src/store/sqlite-db.ts

@@ -57,7 +57,11 @@ CREATE TABLE IF NOT EXISTS observations (
   relatedCommits  TEXT,
   relatedEntities TEXT,
   sourceDetail    TEXT,
-  valueCategory   TEXT
+  valueCategory   TEXT,
+  admissionState  TEXT,
+  admissionReason TEXT,
+  visibility      TEXT,
+  sharedWithAgentIds TEXT
 );
 `;
 
@@ -529,6 +533,8 @@ CREATE INDEX IF NOT EXISTS idx_observations_projectId ON observations(projectId)
 CREATE INDEX IF NOT EXISTS idx_observations_topicKey ON observations(projectId, topicKey);
 CREATE INDEX IF NOT EXISTS idx_observations_status ON observations(status);
 CREATE INDEX IF NOT EXISTS idx_observations_project_status_id ON observations(projectId, status, id);
+CREATE INDEX IF NOT EXISTS idx_observations_project_admission ON observations(projectId, status, admissionState, id);
+CREATE INDEX IF NOT EXISTS idx_observations_project_visibility ON observations(projectId, status, visibility, id);
 CREATE INDEX IF NOT EXISTS idx_mini_skills_projectId ON mini_skills(projectId);
 CREATE INDEX IF NOT EXISTS idx_sessions_projectId ON sessions(projectId);
 CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(projectId, status);
@@ -590,6 +596,22 @@ function addColumnIfMissing(db: any, table: string, column: string, definition:
 }
 
 const SCHEMA_MIGRATIONS: SchemaMigration[] = [
+  {
+    id: '1.2.2-observation-admission',
+    apply: (db) => {
+      addColumnIfMissing(db, 'observations', 'admissionState', 'admissionState TEXT');
+      addColumnIfMissing(db, 'observations', 'admissionReason', 'admissionReason TEXT');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_observations_project_admission ON observations(projectId, status, admissionState, id)');
+    },
+  },
+  {
+    id: '1.2.2-observation-visibility',
+    apply: (db) => {
+      addColumnIfMissing(db, 'observations', 'visibility', 'visibility TEXT');
+      addColumnIfMissing(db, 'observations', 'sharedWithAgentIds', 'sharedWithAgentIds TEXT');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_observations_project_visibility ON observations(projectId, status, visibility, id)');
+    },
+  },
   {
     id: '1.2-code-state-snapshots',
     apply: (db) => {

package/src/store/sqlite-store.ts

@@ -49,6 +49,10 @@ function obsToRow(obs: Observation): Record<string, unknown> {
     relatedEntities: obs.relatedEntities ? JSON.stringify(obs.relatedEntities) : null,
     sourceDetail: obs.sourceDetail ?? null,
     valueCategory: obs.valueCategory ?? null,
+    admissionState: obs.admissionState ?? null,
+    admissionReason: obs.admissionReason ?? null,
+    visibility: obs.visibility ?? null,
+    sharedWithAgentIds: obs.sharedWithAgentIds ? JSON.stringify(obs.sharedWithAgentIds) : null,
     createdByAgentId: obs.createdByAgentId ?? null,
     writeGeneration: obs.writeGeneration ?? 0,
   };
@@ -80,6 +84,10 @@ function rowToObs(row: any): Observation {
     ...(row.relatedEntities ? { relatedEntities: safeJsonParse(row.relatedEntities, []) } : {}),
     ...(row.sourceDetail ? { sourceDetail: row.sourceDetail } : {}),
     ...(row.valueCategory ? { valueCategory: row.valueCategory } : {}),
+    ...(row.admissionState ? { admissionState: row.admissionState } : {}),
+    ...(row.admissionReason ? { admissionReason: row.admissionReason } : {}),
+    ...(row.visibility ? { visibility: row.visibility } : {}),
+    ...(row.sharedWithAgentIds ? { sharedWithAgentIds: safeJsonParse(row.sharedWithAgentIds, []) } : {}),
     ...(row.createdByAgentId ? { createdByAgentId: row.createdByAgentId } : {}),
     ...(row.writeGeneration ? { writeGeneration: row.writeGeneration } : {}),
   } as Observation;
@@ -132,12 +140,14 @@ export class SqliteBackend implements ObservationStore {
         (id, entityName, type, title, narrative, facts, filesModified, concepts, tokens,
          createdAt, updatedAt, projectId, hasCausalLanguage, topicKey, revisionCount,
          sessionId, status, progress, source, commitHash, relatedCommits, relatedEntities,
-         sourceDetail, valueCategory, createdByAgentId, writeGeneration)
+         sourceDetail, valueCategory, admissionState, admissionReason, visibility, sharedWithAgentIds,
+         createdByAgentId, writeGeneration)
       VALUES
         (@id, @entityName, @type, @title, @narrative, @facts, @filesModified, @concepts, @tokens,
          @createdAt, @updatedAt, @projectId, @hasCausalLanguage, @topicKey, @revisionCount,
          @sessionId, @status, @progress, @source, @commitHash, @relatedCommits, @relatedEntities,
-         @sourceDetail, @valueCategory, @createdByAgentId, @writeGeneration)
+         @sourceDetail, @valueCategory, @admissionState, @admissionReason, @visibility, @sharedWithAgentIds,
+         @createdByAgentId, @writeGeneration)
     `);
     this.stmtUpdate = this.stmtInsert; // INSERT OR REPLACE works for both
     this.stmtSetStatus = this.db.prepare(`UPDATE observations SET status = ? WHERE id = ?`);

package/src/team/handoff.ts

@@ -57,6 +57,8 @@ export async function createHandoffArtifact(
     topicKey?: string;
     sourceDetail?: 'explicit' | 'hook' | 'git-ingest';
     valueCategory?: 'core' | 'contextual' | 'ephemeral';
+    visibility?: 'personal' | 'project' | 'team';
+    sharedWithAgentIds?: string[];
     createdByAgentId?: string;
   }) => Promise<{ observation: { id: number }; upserted: boolean }>,
   teamStore: TeamStore,
@@ -82,6 +84,11 @@ export async function createHandoffArtifact(
     topicKey: input.taskId ? `handoff:${input.taskId}:${input.fromAgentId}` : undefined,
     sourceDetail: 'explicit',
     valueCategory: 'core',  // immune to retention archival
+    // A direct handoff is not a project-wide memo. The sender retains access
+    // and the explicit recipient receives a read grant. Broadcast handoffs
+    // are deliberately visible only to active team members.
+    visibility: input.toAgentId ? 'personal' : 'team',
+    ...(input.toAgentId ? { sharedWithAgentIds: [input.toAgentId] } : {}),
     createdByAgentId: input.fromAgentId,
   });
 

package/src/types.ts

@@ -85,6 +85,33 @@ export const OBSERVATION_ICONS: Record<ObservationType, string> = {
 /** Observation lifecycle status */
 export type ObservationStatus = 'active' | 'resolved' | 'archived';
 
+/**
+ * Control-plane admission state for automatically captured observations.
+ * Candidate and ephemeral records remain inspectable, but only qualified
+ * records are eligible for automatic context delivery. Missing state preserves
+ * legacy behavior for observations written before this policy existed.
+ */
+export type ObservationAdmissionState = 'ephemeral' | 'candidate' | 'qualified';
+
+/**
+ * Who may retrieve an observation through agent-facing memory surfaces.
+ * Missing visibility is a legacy record and resolves to `project`.
+ */
+export type ObservationVisibility = 'personal' | 'project' | 'team';
+
+/**
+ * Identity available to an agent-facing retrieval call. Internal maintenance
+ * deliberately omits this and may inspect all project records for lifecycle work.
+ */
+export interface ObservationReader {
+  /** Bound project for a normal project-scoped call. Omit only for explicit global search. */
+  projectId?: string;
+  /** Stable coordination identity, available after an explicit team join. */
+  agentId?: string;
+  /** True only when agentId is an active member of the bound project team. */
+  isTeamMember?: boolean;
+}
+
 /** Progress tracking for task/feature observations */
 export interface ProgressInfo {
   feature: string;
@@ -132,6 +159,14 @@ export interface Observation {
   sourceDetail?: 'explicit' | 'hook' | 'git-ingest';
   /** Value category from formation pipeline evaluation */
   valueCategory?: 'core' | 'contextual' | 'ephemeral';
+  /** Control-plane admission state for automatic capture and delivery. */
+  admissionState?: ObservationAdmissionState;
+  /** Short, sanitized explanation for the latest admission decision. */
+  admissionReason?: string;
+  /** Retrieval scope. Legacy records without a value remain project-visible. */
+  visibility?: ObservationVisibility;
+  /** Explicit additional readers for a personal record, used by targeted handoffs. */
+  sharedWithAgentIds?: string[];
   /** Phase 4a: Agent ID that created this observation (team attribution) */
   createdByAgentId?: string;
   /** Phase 4a: Monotonic write generation — snapshot of storage_generation at write time (watermark coherence) */
@@ -176,6 +211,10 @@ export interface IndexEntry {
   sourceDetail?: 'explicit' | 'hook' | 'git-ingest';
   /** Value category for source-aware ranking */
   valueCategory?: 'core' | 'contextual' | 'ephemeral';
+  /** Control-plane admission state when known. */
+  admissionState?: ObservationAdmissionState;
+  /** Retrieval scope when known. */
+  visibility?: ObservationVisibility;
   /** Explainable recall: why this result matched. */
   matchedFields?: string[];
   /** Entity name — used for entity-affinity scoring and workstream deduplication. */
@@ -216,6 +255,8 @@ export interface SearchOptions {
   source?: 'agent' | 'git' | 'manual';
   /** Internal observability probes can disable access tracking without affecting normal search behavior. */
   trackAccess?: boolean;
+  /** Internal reader context for agent-facing visibility filtering. */
+  reader?: ObservationReader;
 }
 
 /** Topic key family heuristics for suggesting stable topic keys */
@@ -258,6 +299,16 @@ export interface MemorixDocument {
   sourceDetail?: string;
   /** Value category from formation evaluation */
   valueCategory?: string;
+  /** Control-plane admission state for automatic capture and delivery. */
+  admissionState?: string;
+  /** Short, sanitized explanation for the latest admission decision. */
+  admissionReason?: string;
+  /** Retrieval scope for agent-facing filtering. */
+  visibility?: string;
+  /** Agent that owns a personal record, or authored a shared record. */
+  createdByAgentId?: string;
+  /** Explicit readers for a targeted personal record. */
+  sharedWithAgentIds?: string;
   /** Optional vector embedding for semantic/hybrid retrieval */
   embedding?: number[];
   /** Document type: observation or mini-skill (Phase 3a) */

package/src/wiki/generator.ts

@@ -1,4 +1,5 @@
 import type { Observation, MiniSkill } from '../types.js';
+import { isEligibleForKnowledgePromotion } from '../memory/admission.js';
 import type { KnowledgeSourceRef, KnowledgeItem, KnowledgeSection, ProjectKnowledgeOverview } from './types.js';
 
 const COMMAND_LOG_TITLE = /^(Ran:|Command:|Executed:)\s/i;
@@ -63,6 +64,7 @@ function isEligible(o: Observation, projectId: string): boolean {
   if (isCommandLog(o)) return false;
   if (isInactive(o)) return false;
   if (isOtherProject(o, projectId)) return false;
+  if (!isEligibleForKnowledgePromotion(o)) return false;
   if (o.valueCategory === 'ephemeral') return false;
   if (!contextualHasSubstance(o)) return false;
   return true;