memorix 1.2.1 → 1.2.3

package/dist/types.d.ts

@@ -47,6 +47,30 @@ type ObservationType = 'session-request' | 'gotcha' | 'problem-solution' | 'how-
 declare const OBSERVATION_ICONS: Record<ObservationType, string>;
 /** Observation lifecycle status */
 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.
+ */
+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`.
+ */
+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.
+ */
+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 */
 interface ProgressInfo {
     feature: string;
@@ -93,6 +117,14 @@ 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) */
@@ -127,6 +159,10 @@ 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. */
@@ -164,6 +200,8 @@ 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 */
 declare const TOPIC_KEY_FAMILIES: Record<string, string[]>;
@@ -193,6 +231,16 @@ 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) */
@@ -398,4 +446,4 @@ interface MCPConfigAdapter {
     getConfigPath(projectRoot?: string): string;
 }
 
-export { type AgentTarget, DEFAULT_CONFIG, type DetectionFailure, type DetectionFailureReason, type DetectionResult, type DocumentType, type Entity, type IndexEntry, type KnowledgeGraph, type KnowledgeLayer, type MCPConfigAdapter, type MCPServerEntry, type MemorixConfig, type MemorixDocument, type MemoryRef, type MiniSkill, OBSERVATION_ICONS, type Observation, type ObservationRef, type ObservationStatus, type ObservationType, type ProgressInfo, type ProjectInfo, type Relation, type RuleFormatAdapter, type RuleSource, type SearchOptions, type Session, type SkillConflict, type SkillEntry, type SnapshotObservation, type SourceSnapshot, TOPIC_KEY_FAMILIES, type TimelineContext, type UnifiedRule, type WorkflowEntry, type WorkspaceSyncResult };
+export { type AgentTarget, DEFAULT_CONFIG, type DetectionFailure, type DetectionFailureReason, type DetectionResult, type DocumentType, type Entity, type IndexEntry, type KnowledgeGraph, type KnowledgeLayer, type MCPConfigAdapter, type MCPServerEntry, type MemorixConfig, type MemorixDocument, type MemoryRef, type MiniSkill, OBSERVATION_ICONS, type Observation, type ObservationAdmissionState, type ObservationReader, type ObservationRef, type ObservationStatus, type ObservationType, type ObservationVisibility, type ProgressInfo, type ProjectInfo, type Relation, type RuleFormatAdapter, type RuleSource, type SearchOptions, type Session, type SkillConflict, type SkillEntry, type SnapshotObservation, type SourceSnapshot, TOPIC_KEY_FAMILIES, type TimelineContext, type UnifiedRule, type WorkflowEntry, type WorkspaceSyncResult };

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Memorix Core Types\n *\n * Data model sources:\n * - Entity/Relation/KnowledgeGraph: MCP Official Memory Server (v0.6.3)\n * - Observation/ObservationType: claude-mem Progressive Disclosure\n * - UnifiedRule/RuleSource: Memorix original (rules sync)\n *\n * Designed for extensibility: new agent formats (Kiro, Copilot, Antigravity)\n * can be added by extending RuleSource and adding format adapters.\n */\n\n// ============================================================\n// Knowledge Graph (adopted from MCP Official Memory Server)\n// ============================================================\n\n/** A node in the knowledge graph representing a concept, component, or config */\nexport interface Entity {\n  name: string;\n  entityType: string;\n  observations: string[];\n}\n\n/** A directed edge between two entities */\nexport interface Relation {\n  from: string;\n  to: string;\n  relationType: string;\n}\n\n/** The complete knowledge graph */\nexport interface KnowledgeGraph {\n  entities: Entity[];\n  relations: Relation[];\n}\n\n// ============================================================\n// Observation (adopted from claude-mem Progressive Disclosure)\n// ============================================================\n\n/**\n * Observation type classification using claude-mem's icon-based legend system.\n *\n * Icon mapping:\n * [SESSION] session-request   — User's original goal\n * [GOTCHA] gotcha            — Critical pitfall / trap\n * [FIX] problem-solution  — Bug fix or workaround\n * [INFO] how-it-works      — Technical explanation\n * [CHANGE] what-changed      — Code/architecture change\n * [DISCOVERY] discovery         — New learning or insight\n * [WHY] why-it-exists     — Design rationale\n * [DECISION] decision          — Architecture decision\n * [TRADEOFF] trade-off         — Deliberate compromise\n * [REASONING] reasoning         — Why this approach was chosen (System 2 reasoning trace)\n * [PROBE] probe                — Operational heartbeat / connectivity check (short-lived, excluded from default search)\n */\nexport type ObservationType =\n  | 'session-request'\n  | 'gotcha'\n  | 'problem-solution'\n  | 'how-it-works'\n  | 'what-changed'\n  | 'discovery'\n  | 'why-it-exists'\n  | 'decision'\n  | 'trade-off'\n  | 'reasoning'\n  | 'probe';\n\n/** Map from ObservationType to display icon */\nexport const OBSERVATION_ICONS: Record<ObservationType, string> = {\n  'session-request': '[SESSION]',\n  'gotcha': '[GOTCHA]',\n  'problem-solution': '[FIX]',\n  'how-it-works': '[INFO]',\n  'what-changed': '[CHANGE]',\n  'discovery': '[DISCOVERY]',\n  'why-it-exists': '[WHY]',\n  'decision': '[DECISION]',\n  'trade-off': '[TRADEOFF]',\n  'reasoning': '[REASONING]',\n  'probe': '[PROBE]',\n};\n\n/** Observation lifecycle status */\nexport type ObservationStatus = 'active' | 'resolved' | 'archived';\n\n/** Progress tracking for task/feature observations */\nexport interface ProgressInfo {\n  feature: string;\n  status: 'in-progress' | 'completed' | 'blocked';\n  completion?: number;\n}\n\n/** A rich observation record attached to an entity */\nexport interface Observation {\n  id: number;\n  entityName: string;\n  type: ObservationType;\n  title: string;\n  narrative: string;\n  facts: string[];\n  filesModified: string[];\n  concepts: string[];\n  tokens: number;\n  createdAt: string;\n  updatedAt?: string;\n  projectId: string;\n  /** Whether the observation contains causal language (because, due to, etc.) */\n  hasCausalLanguage?: boolean;\n  /** Optional topic key for upsert — same project+topicKey updates existing observation */\n  topicKey?: string;\n  /** How many times this observation was revised via topic key upsert (starts at 1) */\n  revisionCount?: number;\n  /** Session ID this observation belongs to */\n  sessionId?: string;\n  /** Lifecycle status: active (default) → resolved → archived */\n  status?: ObservationStatus;\n  /** ID of the observation that superseded this one (set when auto-resolved by topicKey upsert) */\n  supersededBy?: number;\n  /** Progress tracking for task/feature observations */\n  progress?: ProgressInfo;\n  /** Origin of this observation: agent (IDE hooks/MCP), git (commit ingest), manual (CLI) */\n  source?: 'agent' | 'git' | 'manual';\n  /** Git commit hash if source is 'git' */\n  commitHash?: string;\n  /** Related commit hashes — links reasoning memories to the commits they explain */\n  relatedCommits?: string[];\n  /** Related entity names — explicit cross-references to other memory entities */\n  relatedEntities?: string[];\n  /** Provenance detail: how this observation entered the system */\n  sourceDetail?: 'explicit' | 'hook' | 'git-ingest';\n  /** Value category from formation pipeline evaluation */\n  valueCategory?: 'core' | 'contextual' | 'ephemeral';\n  /** Phase 4a: Agent ID that created this observation (team attribution) */\n  createdByAgentId?: string;\n  /** Phase 4a: Monotonic write generation — snapshot of storage_generation at write time (watermark coherence) */\n  writeGeneration?: number;\n}\n\n// ============================================================\n// Session Lifecycle (inspired by Engram's session management)\n// ============================================================\n\n/** A coding session tracked by Memorix */\nexport interface Session {\n  id: string;\n  projectId: string;\n  startedAt: string;\n  endedAt?: string;\n  summary?: string;\n  status: 'active' | 'completed';\n  /** Agent/IDE that started this session */\n  agent?: string;\n}\n\n// ============================================================\n// Compact Engine (adopted from claude-mem 3-layer workflow)\n// ============================================================\n\n/** L1 index entry — lightweight, ~50-100 tokens per result */\nexport interface IndexEntry {\n  id: number;\n  time: string;\n  type: ObservationType;\n  icon: string;\n  title: string;\n  tokens: number;\n  /** Relevance score from search (time-decayed). Used by compact engine. */\n  score?: number;\n  /** Project that owns this observation. Needed to disambiguate global results. */\n  projectId?: string;\n  /** Origin of the memory for source-aware retrieval and display. */\n  source?: 'agent' | 'git' | 'manual';\n  /** Provenance detail for source-aware display */\n  sourceDetail?: 'explicit' | 'hook' | 'git-ingest';\n  /** Value category for source-aware ranking */\n  valueCategory?: 'core' | 'contextual' | 'ephemeral';\n  /** Explainable recall: why this result matched. */\n  matchedFields?: string[];\n  /** Entity name — used for entity-affinity scoring and workstream deduplication. */\n  entityName?: string;\n  /** Document type: observation or mini-skill (Phase 3a) */\n  documentType?: DocumentType;\n  /** Knowledge layer for layer-aware ranking (Phase 3a) */\n  knowledgeLayer?: KnowledgeLayer;\n}\n\n/** Explicit reference to an observation, optionally scoped to a project. */\nexport interface ObservationRef {\n  id: number;\n  projectId?: string;\n}\n\n/** L2 timeline context — observations around an anchor */\nexport interface TimelineContext {\n  anchorId: number;\n  anchorEntry: IndexEntry | null;\n  before: IndexEntry[];\n  after: IndexEntry[];\n}\n\n/** Search options for the compact engine */\nexport interface SearchOptions {\n  query: string;\n  limit?: number;\n  type?: ObservationType;\n  projectId?: string;\n  since?: string;\n  until?: string;\n  /** Token budget — trim results to fit within this many tokens (0 = unlimited) */\n  maxTokens?: number;\n  /** Filter by observation status. Default: 'active' (only show active memories) */\n  status?: ObservationStatus | 'all';\n  /** Filter by observation source: 'agent', 'git', 'manual', or undefined for all */\n  source?: 'agent' | 'git' | 'manual';\n  /** Internal observability probes can disable access tracking without affecting normal search behavior. */\n  trackAccess?: boolean;\n}\n\n/** Topic key family heuristics for suggesting stable topic keys */\nexport const TOPIC_KEY_FAMILIES: Record<string, string[]> = {\n  'architecture': ['architecture', 'design', 'adr', 'structure', 'pattern'],\n  'bug': ['bugfix', 'fix', 'error', 'regression', 'crash', 'problem-solution'],\n  'decision': ['decision', 'trade-off', 'choice', 'strategy'],\n  'config': ['config', 'setup', 'env', 'environment', 'deployment'],\n  'discovery': ['discovery', 'learning', 'insight', 'gotcha'],\n  'pattern': ['pattern', 'convention', 'standard', 'best-practice'],\n};\n\n// ============================================================\n// Orama Document Schema\n// ============================================================\n\n/** The document shape stored in Orama */\nexport interface MemorixDocument {\n  id: string;\n  observationId: number;\n  entityName: string;\n  type: string;\n  title: string;\n  narrative: string;\n  facts: string;\n  filesModified: string;\n  concepts: string;\n  tokens: number;\n  createdAt: string;\n  projectId: string;\n  /** Number of times this observation was returned in search results */\n  accessCount: number;\n  /** ISO timestamp of last access via search/detail */\n  lastAccessedAt: string;\n  /** Lifecycle status: active, resolved, archived */\n  status: string;\n  /** Origin: agent, git, manual */\n  source: string;\n  /** Provenance detail: explicit, hook, or git-ingest */\n  sourceDetail?: string;\n  /** Value category from formation evaluation */\n  valueCategory?: string;\n  /** Optional vector embedding for semantic/hybrid retrieval */\n  embedding?: number[];\n  /** Document type: observation or mini-skill (Phase 3a) */\n  documentType?: DocumentType;\n  /** Knowledge layer for layer-aware ranking (Phase 3a) */\n  knowledgeLayer?: KnowledgeLayer;\n}\n\n// ============================================================\n// Rules System (Memorix original — extensible for new agents)\n// ============================================================\n\n/**\n * Supported agent/IDE rule sources.\n * All 7 major AI IDEs are supported.\n */\nexport type RuleSource =\n  | 'cursor'\n  | 'claude-code'\n  | 'codex'\n  | 'windsurf'\n  | 'antigravity'\n  | 'gemini-cli'\n  | 'copilot'\n  | 'kiro'\n  | 'trae'\n  | 'memorix';\n\n/** A parsed rule in the unified intermediate representation */\nexport interface UnifiedRule {\n  id: string;\n  content: string;\n  description?: string;\n  source: RuleSource;\n  scope: 'global' | 'project' | 'path-specific';\n  paths?: string[];\n  alwaysApply?: boolean;\n  priority: number;\n  hash: string;\n}\n\n/**\n * Format adapter interface — implement this for each agent/IDE.\n * Adding a new agent (e.g., Kiro) only requires implementing this interface.\n */\nexport interface RuleFormatAdapter {\n  /** Unique identifier for this agent format */\n  readonly source: RuleSource;\n\n  /** File paths/globs this adapter can parse */\n  readonly filePatterns: string[];\n\n  /** Parse rule files into unified representation */\n  parse(filePath: string, content: string): UnifiedRule[];\n\n  /** Generate rule file content from unified representation */\n  generate(rules: UnifiedRule[]): { filePath: string; content: string }[];\n}\n\n// ============================================================\n// Project Identity\n// ============================================================\n\nexport interface ProjectInfo {\n  id: string;\n  name: string;\n  gitRemote?: string;\n  rootPath: string;\n}\n\n/**\n * Diagnostic failure info from project detection.\n * Tells callers exactly WHY detection failed so they can report actionable errors.\n */\nexport type DetectionFailureReason =\n  | 'path_not_found'\n  | 'not_a_directory'\n  | 'no_git'\n  | 'git_worktree_error'\n  | 'git_safe_directory'\n  | 'remote_resolve_failed';\n\nexport interface DetectionFailure {\n  reason: DetectionFailureReason;\n  path: string;\n  detail: string;\n}\n\nexport interface DetectionResult {\n  project: ProjectInfo | null;\n  failure: DetectionFailure | null;\n}\n\n// ============================================================\n// Memorix Server Configuration\n// ============================================================\n\nexport interface MemorixConfig {\n  dataDir: string;\n  projectId: string;\n  projectName: string;\n  enableEmbeddings: boolean;\n  enableRulesSync: boolean;\n  watchRuleFiles: boolean;\n}\n\nexport const DEFAULT_CONFIG: Partial<MemorixConfig> = {\n  enableEmbeddings: false,\n  enableRulesSync: false,\n  watchRuleFiles: false,\n};\n\n// ============================================================\n// Workspace Sync — Cross-Agent workspace migration\n// ============================================================\n\n/** Supported agent targets for workspace sync */\nexport type AgentTarget =\n  | 'windsurf'\n  | 'cursor'\n  | 'claude-code'\n  | 'codex'\n  | 'copilot'\n  | 'antigravity'\n  | 'gemini-cli'\n  | 'openclaw'\n  | 'hermes'\n  | 'omp'\n  | 'kiro'\n  | 'opencode'\n  | 'trae';\n\n/** A unified MCP server entry across all agent config formats */\nexport interface MCPServerEntry {\n  name: string;\n  /** Command for stdio transport */\n  command: string;\n  /** Args for stdio transport */\n  args: string[];\n  /** Environment variables */\n  env?: Record<string, string> | null;\n  /** URL for HTTP/SSE transport (Codex uses `url`, Windsurf uses `serverUrl`) */\n  url?: string;\n  /** HTTP headers (Windsurf uses `headers` for HTTP transport) */\n  headers?: Record<string, string>;\n  /** Whether this server is disabled */\n  disabled?: boolean;\n  /** Claude Code: force small core tool sets to load before the first prompt */\n  alwaysLoad?: boolean;\n}\n\n/** Unified workflow entry */\nexport interface WorkflowEntry {\n  name: string;\n  description: string;\n  content: string;\n  source: AgentTarget;\n  filePath: string;\n}\n\n/** A skill folder discovered from an agent's skills directory */\nexport interface SkillEntry {\n  name: string;\n  description: string;\n  sourcePath: string;\n  sourceAgent: AgentTarget;\n}\n\n/** Conflict when two agents have a skill with the same folder name */\nexport interface SkillConflict {\n  name: string;\n  kept: SkillEntry;\n  skipped: SkillEntry;\n}\n\n/** Result of a workspace sync operation */\nexport interface WorkspaceSyncResult {\n  mcpServers: {\n    scanned: MCPServerEntry[];\n    generated: { filePath: string; content: string }[];\n  };\n  workflows: {\n    scanned: WorkflowEntry[];\n    generated: { filePath: string; content: string }[];\n  };\n  rules: {\n    scanned: number;\n    generated: number;\n  };\n  skills: {\n    scanned: SkillEntry[];\n    conflicts: SkillConflict[];\n    copied: string[];\n    skipped: string[];\n  };\n}\n\n// ============================================================\n// Mini-Skills — Promoted memories that never decay\n// ============================================================\n\n/** A mini-skill promoted from one or more observations */\nexport interface MiniSkill {\n  id: number;\n  /** Observation IDs this mini-skill was derived from (live refs, best-effort) */\n  sourceObservationIds: number[];\n  /** Entity the source observations belong to */\n  sourceEntity: string;\n  /** Short title for the skill */\n  title: string;\n  /** What the agent should do (imperative instruction) */\n  instruction: string;\n  /** When this skill should be applied (scenario description) */\n  trigger: string;\n  /** Key facts extracted from source observations */\n  facts: string[];\n  /** Project this skill belongs to */\n  projectId: string;\n  /** ISO timestamp */\n  createdAt: string;\n  /** How many times this skill was injected in session_start */\n  usedCount: number;\n  /** Classification tags */\n  tags: string[];\n  /** Frozen source observation content at promote time (JSON, immutable provenance proof) */\n  sourceSnapshot?: string;\n  /** ISO timestamp of last modification (Phase 3a: set once at creation) */\n  updatedAt?: string;\n}\n\n// ============================================================\n// Source Snapshot — immutable provenance proof for promoted knowledge\n// ============================================================\n\n/** A single observation entry within a source snapshot */\nexport interface SnapshotObservation {\n  id: number;\n  title: string;\n  type: string;\n  narrative: string;\n  facts: string[];\n  entityName: string;\n  projectId: string;\n  createdAt: string;\n  /** Frozen source detail for provenance (explicit / hook / git-ingest) */\n  sourceDetail?: string;\n}\n\n/** Frozen source content captured at promote time */\nexport interface SourceSnapshot {\n  observations: SnapshotObservation[];\n  promotedAt: string;\n}\n\n// ============================================================\n// Knowledge Layer — Phase 3a retrieval classification\n// ============================================================\n\n/** Classification of knowledge for layer-aware ranking */\nexport type KnowledgeLayer = 'project-truth' | 'promoted' | 'evidence';\n\n/** Document type discriminator for Orama index */\nexport type DocumentType = 'observation' | 'mini-skill';\n\n// ============================================================\n// Typed Memory Reference — Phase 3a reference protocol\n// ============================================================\n\n/** A typed reference to a memory object (observation or mini-skill) */\nexport interface MemoryRef {\n  kind: 'obs' | 'skill';\n  id: number;\n  projectId?: string;\n}\n\n/** MCP config format adapter interface */\nexport interface MCPConfigAdapter {\n  readonly source: AgentTarget;\n  /** Parse MCP server entries from a config file */\n  parse(content: string): MCPServerEntry[];\n  /** Generate config file content from MCP server entries */\n  generate(servers: MCPServerEntry[]): string;\n  /** Get the default config file path for this agent */\n  getConfigPath(projectRoot?: string): string;\n}\n"],"mappings":";AAsEO,IAAM,oBAAqD;AAAA,EAChE,mBAAmB;AAAA,EACnB,UAAU;AAAA,EACV,oBAAoB;AAAA,EACpB,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,aAAa;AAAA,EACb,iBAAiB;AAAA,EACjB,YAAY;AAAA,EACZ,aAAa;AAAA,EACb,aAAa;AAAA,EACb,SAAS;AACX;AA2IO,IAAM,qBAA+C;AAAA,EAC1D,gBAAgB,CAAC,gBAAgB,UAAU,OAAO,aAAa,SAAS;AAAA,EACxE,OAAO,CAAC,UAAU,OAAO,SAAS,cAAc,SAAS,kBAAkB;AAAA,EAC3E,YAAY,CAAC,YAAY,aAAa,UAAU,UAAU;AAAA,EAC1D,UAAU,CAAC,UAAU,SAAS,OAAO,eAAe,YAAY;AAAA,EAChE,aAAa,CAAC,aAAa,YAAY,WAAW,QAAQ;AAAA,EAC1D,WAAW,CAAC,WAAW,cAAc,YAAY,eAAe;AAClE;AA0IO,IAAM,iBAAyC;AAAA,EACpD,kBAAkB;AAAA,EAClB,iBAAiB;AAAA,EACjB,gBAAgB;AAClB;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * Memorix Core Types\n *\n * Data model sources:\n * - Entity/Relation/KnowledgeGraph: MCP Official Memory Server (v0.6.3)\n * - Observation/ObservationType: claude-mem Progressive Disclosure\n * - UnifiedRule/RuleSource: Memorix original (rules sync)\n *\n * Designed for extensibility: new agent formats (Kiro, Copilot, Antigravity)\n * can be added by extending RuleSource and adding format adapters.\n */\n\n// ============================================================\n// Knowledge Graph (adopted from MCP Official Memory Server)\n// ============================================================\n\n/** A node in the knowledge graph representing a concept, component, or config */\nexport interface Entity {\n  name: string;\n  entityType: string;\n  observations: string[];\n}\n\n/** A directed edge between two entities */\nexport interface Relation {\n  from: string;\n  to: string;\n  relationType: string;\n}\n\n/** The complete knowledge graph */\nexport interface KnowledgeGraph {\n  entities: Entity[];\n  relations: Relation[];\n}\n\n// ============================================================\n// Observation (adopted from claude-mem Progressive Disclosure)\n// ============================================================\n\n/**\n * Observation type classification using claude-mem's icon-based legend system.\n *\n * Icon mapping:\n * [SESSION] session-request   — User's original goal\n * [GOTCHA] gotcha            — Critical pitfall / trap\n * [FIX] problem-solution  — Bug fix or workaround\n * [INFO] how-it-works      — Technical explanation\n * [CHANGE] what-changed      — Code/architecture change\n * [DISCOVERY] discovery         — New learning or insight\n * [WHY] why-it-exists     — Design rationale\n * [DECISION] decision          — Architecture decision\n * [TRADEOFF] trade-off         — Deliberate compromise\n * [REASONING] reasoning         — Why this approach was chosen (System 2 reasoning trace)\n * [PROBE] probe                — Operational heartbeat / connectivity check (short-lived, excluded from default search)\n */\nexport type ObservationType =\n  | 'session-request'\n  | 'gotcha'\n  | 'problem-solution'\n  | 'how-it-works'\n  | 'what-changed'\n  | 'discovery'\n  | 'why-it-exists'\n  | 'decision'\n  | 'trade-off'\n  | 'reasoning'\n  | 'probe';\n\n/** Map from ObservationType to display icon */\nexport const OBSERVATION_ICONS: Record<ObservationType, string> = {\n  'session-request': '[SESSION]',\n  'gotcha': '[GOTCHA]',\n  'problem-solution': '[FIX]',\n  'how-it-works': '[INFO]',\n  'what-changed': '[CHANGE]',\n  'discovery': '[DISCOVERY]',\n  'why-it-exists': '[WHY]',\n  'decision': '[DECISION]',\n  'trade-off': '[TRADEOFF]',\n  'reasoning': '[REASONING]',\n  'probe': '[PROBE]',\n};\n\n/** Observation lifecycle status */\nexport type ObservationStatus = 'active' | 'resolved' | 'archived';\n\n/**\n * Control-plane admission state for automatically captured observations.\n * Candidate and ephemeral records remain inspectable, but only qualified\n * records are eligible for automatic context delivery. Missing state preserves\n * legacy behavior for observations written before this policy existed.\n */\nexport type ObservationAdmissionState = 'ephemeral' | 'candidate' | 'qualified';\n\n/**\n * Who may retrieve an observation through agent-facing memory surfaces.\n * Missing visibility is a legacy record and resolves to `project`.\n */\nexport type ObservationVisibility = 'personal' | 'project' | 'team';\n\n/**\n * Identity available to an agent-facing retrieval call. Internal maintenance\n * deliberately omits this and may inspect all project records for lifecycle work.\n */\nexport interface ObservationReader {\n  /** Bound project for a normal project-scoped call. Omit only for explicit global search. */\n  projectId?: string;\n  /** Stable coordination identity, available after an explicit team join. */\n  agentId?: string;\n  /** True only when agentId is an active member of the bound project team. */\n  isTeamMember?: boolean;\n}\n\n/** Progress tracking for task/feature observations */\nexport interface ProgressInfo {\n  feature: string;\n  status: 'in-progress' | 'completed' | 'blocked';\n  completion?: number;\n}\n\n/** A rich observation record attached to an entity */\nexport interface Observation {\n  id: number;\n  entityName: string;\n  type: ObservationType;\n  title: string;\n  narrative: string;\n  facts: string[];\n  filesModified: string[];\n  concepts: string[];\n  tokens: number;\n  createdAt: string;\n  updatedAt?: string;\n  projectId: string;\n  /** Whether the observation contains causal language (because, due to, etc.) */\n  hasCausalLanguage?: boolean;\n  /** Optional topic key for upsert — same project+topicKey updates existing observation */\n  topicKey?: string;\n  /** How many times this observation was revised via topic key upsert (starts at 1) */\n  revisionCount?: number;\n  /** Session ID this observation belongs to */\n  sessionId?: string;\n  /** Lifecycle status: active (default) → resolved → archived */\n  status?: ObservationStatus;\n  /** ID of the observation that superseded this one (set when auto-resolved by topicKey upsert) */\n  supersededBy?: number;\n  /** Progress tracking for task/feature observations */\n  progress?: ProgressInfo;\n  /** Origin of this observation: agent (IDE hooks/MCP), git (commit ingest), manual (CLI) */\n  source?: 'agent' | 'git' | 'manual';\n  /** Git commit hash if source is 'git' */\n  commitHash?: string;\n  /** Related commit hashes — links reasoning memories to the commits they explain */\n  relatedCommits?: string[];\n  /** Related entity names — explicit cross-references to other memory entities */\n  relatedEntities?: string[];\n  /** Provenance detail: how this observation entered the system */\n  sourceDetail?: 'explicit' | 'hook' | 'git-ingest';\n  /** Value category from formation pipeline evaluation */\n  valueCategory?: 'core' | 'contextual' | 'ephemeral';\n  /** Control-plane admission state for automatic capture and delivery. */\n  admissionState?: ObservationAdmissionState;\n  /** Short, sanitized explanation for the latest admission decision. */\n  admissionReason?: string;\n  /** Retrieval scope. Legacy records without a value remain project-visible. */\n  visibility?: ObservationVisibility;\n  /** Explicit additional readers for a personal record, used by targeted handoffs. */\n  sharedWithAgentIds?: string[];\n  /** Phase 4a: Agent ID that created this observation (team attribution) */\n  createdByAgentId?: string;\n  /** Phase 4a: Monotonic write generation — snapshot of storage_generation at write time (watermark coherence) */\n  writeGeneration?: number;\n}\n\n// ============================================================\n// Session Lifecycle (inspired by Engram's session management)\n// ============================================================\n\n/** A coding session tracked by Memorix */\nexport interface Session {\n  id: string;\n  projectId: string;\n  startedAt: string;\n  endedAt?: string;\n  summary?: string;\n  status: 'active' | 'completed';\n  /** Agent/IDE that started this session */\n  agent?: string;\n}\n\n// ============================================================\n// Compact Engine (adopted from claude-mem 3-layer workflow)\n// ============================================================\n\n/** L1 index entry — lightweight, ~50-100 tokens per result */\nexport interface IndexEntry {\n  id: number;\n  time: string;\n  type: ObservationType;\n  icon: string;\n  title: string;\n  tokens: number;\n  /** Relevance score from search (time-decayed). Used by compact engine. */\n  score?: number;\n  /** Project that owns this observation. Needed to disambiguate global results. */\n  projectId?: string;\n  /** Origin of the memory for source-aware retrieval and display. */\n  source?: 'agent' | 'git' | 'manual';\n  /** Provenance detail for source-aware display */\n  sourceDetail?: 'explicit' | 'hook' | 'git-ingest';\n  /** Value category for source-aware ranking */\n  valueCategory?: 'core' | 'contextual' | 'ephemeral';\n  /** Control-plane admission state when known. */\n  admissionState?: ObservationAdmissionState;\n  /** Retrieval scope when known. */\n  visibility?: ObservationVisibility;\n  /** Explainable recall: why this result matched. */\n  matchedFields?: string[];\n  /** Entity name — used for entity-affinity scoring and workstream deduplication. */\n  entityName?: string;\n  /** Document type: observation or mini-skill (Phase 3a) */\n  documentType?: DocumentType;\n  /** Knowledge layer for layer-aware ranking (Phase 3a) */\n  knowledgeLayer?: KnowledgeLayer;\n}\n\n/** Explicit reference to an observation, optionally scoped to a project. */\nexport interface ObservationRef {\n  id: number;\n  projectId?: string;\n}\n\n/** L2 timeline context — observations around an anchor */\nexport interface TimelineContext {\n  anchorId: number;\n  anchorEntry: IndexEntry | null;\n  before: IndexEntry[];\n  after: IndexEntry[];\n}\n\n/** Search options for the compact engine */\nexport interface SearchOptions {\n  query: string;\n  limit?: number;\n  type?: ObservationType;\n  projectId?: string;\n  since?: string;\n  until?: string;\n  /** Token budget — trim results to fit within this many tokens (0 = unlimited) */\n  maxTokens?: number;\n  /** Filter by observation status. Default: 'active' (only show active memories) */\n  status?: ObservationStatus | 'all';\n  /** Filter by observation source: 'agent', 'git', 'manual', or undefined for all */\n  source?: 'agent' | 'git' | 'manual';\n  /** Internal observability probes can disable access tracking without affecting normal search behavior. */\n  trackAccess?: boolean;\n  /** Internal reader context for agent-facing visibility filtering. */\n  reader?: ObservationReader;\n}\n\n/** Topic key family heuristics for suggesting stable topic keys */\nexport const TOPIC_KEY_FAMILIES: Record<string, string[]> = {\n  'architecture': ['architecture', 'design', 'adr', 'structure', 'pattern'],\n  'bug': ['bugfix', 'fix', 'error', 'regression', 'crash', 'problem-solution'],\n  'decision': ['decision', 'trade-off', 'choice', 'strategy'],\n  'config': ['config', 'setup', 'env', 'environment', 'deployment'],\n  'discovery': ['discovery', 'learning', 'insight', 'gotcha'],\n  'pattern': ['pattern', 'convention', 'standard', 'best-practice'],\n};\n\n// ============================================================\n// Orama Document Schema\n// ============================================================\n\n/** The document shape stored in Orama */\nexport interface MemorixDocument {\n  id: string;\n  observationId: number;\n  entityName: string;\n  type: string;\n  title: string;\n  narrative: string;\n  facts: string;\n  filesModified: string;\n  concepts: string;\n  tokens: number;\n  createdAt: string;\n  projectId: string;\n  /** Number of times this observation was returned in search results */\n  accessCount: number;\n  /** ISO timestamp of last access via search/detail */\n  lastAccessedAt: string;\n  /** Lifecycle status: active, resolved, archived */\n  status: string;\n  /** Origin: agent, git, manual */\n  source: string;\n  /** Provenance detail: explicit, hook, or git-ingest */\n  sourceDetail?: string;\n  /** Value category from formation evaluation */\n  valueCategory?: string;\n  /** Control-plane admission state for automatic capture and delivery. */\n  admissionState?: string;\n  /** Short, sanitized explanation for the latest admission decision. */\n  admissionReason?: string;\n  /** Retrieval scope for agent-facing filtering. */\n  visibility?: string;\n  /** Agent that owns a personal record, or authored a shared record. */\n  createdByAgentId?: string;\n  /** Explicit readers for a targeted personal record. */\n  sharedWithAgentIds?: string;\n  /** Optional vector embedding for semantic/hybrid retrieval */\n  embedding?: number[];\n  /** Document type: observation or mini-skill (Phase 3a) */\n  documentType?: DocumentType;\n  /** Knowledge layer for layer-aware ranking (Phase 3a) */\n  knowledgeLayer?: KnowledgeLayer;\n}\n\n// ============================================================\n// Rules System (Memorix original — extensible for new agents)\n// ============================================================\n\n/**\n * Supported agent/IDE rule sources.\n * All 7 major AI IDEs are supported.\n */\nexport type RuleSource =\n  | 'cursor'\n  | 'claude-code'\n  | 'codex'\n  | 'windsurf'\n  | 'antigravity'\n  | 'gemini-cli'\n  | 'copilot'\n  | 'kiro'\n  | 'trae'\n  | 'memorix';\n\n/** A parsed rule in the unified intermediate representation */\nexport interface UnifiedRule {\n  id: string;\n  content: string;\n  description?: string;\n  source: RuleSource;\n  scope: 'global' | 'project' | 'path-specific';\n  paths?: string[];\n  alwaysApply?: boolean;\n  priority: number;\n  hash: string;\n}\n\n/**\n * Format adapter interface — implement this for each agent/IDE.\n * Adding a new agent (e.g., Kiro) only requires implementing this interface.\n */\nexport interface RuleFormatAdapter {\n  /** Unique identifier for this agent format */\n  readonly source: RuleSource;\n\n  /** File paths/globs this adapter can parse */\n  readonly filePatterns: string[];\n\n  /** Parse rule files into unified representation */\n  parse(filePath: string, content: string): UnifiedRule[];\n\n  /** Generate rule file content from unified representation */\n  generate(rules: UnifiedRule[]): { filePath: string; content: string }[];\n}\n\n// ============================================================\n// Project Identity\n// ============================================================\n\nexport interface ProjectInfo {\n  id: string;\n  name: string;\n  gitRemote?: string;\n  rootPath: string;\n}\n\n/**\n * Diagnostic failure info from project detection.\n * Tells callers exactly WHY detection failed so they can report actionable errors.\n */\nexport type DetectionFailureReason =\n  | 'path_not_found'\n  | 'not_a_directory'\n  | 'no_git'\n  | 'git_worktree_error'\n  | 'git_safe_directory'\n  | 'remote_resolve_failed';\n\nexport interface DetectionFailure {\n  reason: DetectionFailureReason;\n  path: string;\n  detail: string;\n}\n\nexport interface DetectionResult {\n  project: ProjectInfo | null;\n  failure: DetectionFailure | null;\n}\n\n// ============================================================\n// Memorix Server Configuration\n// ============================================================\n\nexport interface MemorixConfig {\n  dataDir: string;\n  projectId: string;\n  projectName: string;\n  enableEmbeddings: boolean;\n  enableRulesSync: boolean;\n  watchRuleFiles: boolean;\n}\n\nexport const DEFAULT_CONFIG: Partial<MemorixConfig> = {\n  enableEmbeddings: false,\n  enableRulesSync: false,\n  watchRuleFiles: false,\n};\n\n// ============================================================\n// Workspace Sync — Cross-Agent workspace migration\n// ============================================================\n\n/** Supported agent targets for workspace sync */\nexport type AgentTarget =\n  | 'windsurf'\n  | 'cursor'\n  | 'claude-code'\n  | 'codex'\n  | 'copilot'\n  | 'antigravity'\n  | 'gemini-cli'\n  | 'openclaw'\n  | 'hermes'\n  | 'omp'\n  | 'kiro'\n  | 'opencode'\n  | 'trae';\n\n/** A unified MCP server entry across all agent config formats */\nexport interface MCPServerEntry {\n  name: string;\n  /** Command for stdio transport */\n  command: string;\n  /** Args for stdio transport */\n  args: string[];\n  /** Environment variables */\n  env?: Record<string, string> | null;\n  /** URL for HTTP/SSE transport (Codex uses `url`, Windsurf uses `serverUrl`) */\n  url?: string;\n  /** HTTP headers (Windsurf uses `headers` for HTTP transport) */\n  headers?: Record<string, string>;\n  /** Whether this server is disabled */\n  disabled?: boolean;\n  /** Claude Code: force small core tool sets to load before the first prompt */\n  alwaysLoad?: boolean;\n}\n\n/** Unified workflow entry */\nexport interface WorkflowEntry {\n  name: string;\n  description: string;\n  content: string;\n  source: AgentTarget;\n  filePath: string;\n}\n\n/** A skill folder discovered from an agent's skills directory */\nexport interface SkillEntry {\n  name: string;\n  description: string;\n  sourcePath: string;\n  sourceAgent: AgentTarget;\n}\n\n/** Conflict when two agents have a skill with the same folder name */\nexport interface SkillConflict {\n  name: string;\n  kept: SkillEntry;\n  skipped: SkillEntry;\n}\n\n/** Result of a workspace sync operation */\nexport interface WorkspaceSyncResult {\n  mcpServers: {\n    scanned: MCPServerEntry[];\n    generated: { filePath: string; content: string }[];\n  };\n  workflows: {\n    scanned: WorkflowEntry[];\n    generated: { filePath: string; content: string }[];\n  };\n  rules: {\n    scanned: number;\n    generated: number;\n  };\n  skills: {\n    scanned: SkillEntry[];\n    conflicts: SkillConflict[];\n    copied: string[];\n    skipped: string[];\n  };\n}\n\n// ============================================================\n// Mini-Skills — Promoted memories that never decay\n// ============================================================\n\n/** A mini-skill promoted from one or more observations */\nexport interface MiniSkill {\n  id: number;\n  /** Observation IDs this mini-skill was derived from (live refs, best-effort) */\n  sourceObservationIds: number[];\n  /** Entity the source observations belong to */\n  sourceEntity: string;\n  /** Short title for the skill */\n  title: string;\n  /** What the agent should do (imperative instruction) */\n  instruction: string;\n  /** When this skill should be applied (scenario description) */\n  trigger: string;\n  /** Key facts extracted from source observations */\n  facts: string[];\n  /** Project this skill belongs to */\n  projectId: string;\n  /** ISO timestamp */\n  createdAt: string;\n  /** How many times this skill was injected in session_start */\n  usedCount: number;\n  /** Classification tags */\n  tags: string[];\n  /** Frozen source observation content at promote time (JSON, immutable provenance proof) */\n  sourceSnapshot?: string;\n  /** ISO timestamp of last modification (Phase 3a: set once at creation) */\n  updatedAt?: string;\n}\n\n// ============================================================\n// Source Snapshot — immutable provenance proof for promoted knowledge\n// ============================================================\n\n/** A single observation entry within a source snapshot */\nexport interface SnapshotObservation {\n  id: number;\n  title: string;\n  type: string;\n  narrative: string;\n  facts: string[];\n  entityName: string;\n  projectId: string;\n  createdAt: string;\n  /** Frozen source detail for provenance (explicit / hook / git-ingest) */\n  sourceDetail?: string;\n}\n\n/** Frozen source content captured at promote time */\nexport interface SourceSnapshot {\n  observations: SnapshotObservation[];\n  promotedAt: string;\n}\n\n// ============================================================\n// Knowledge Layer — Phase 3a retrieval classification\n// ============================================================\n\n/** Classification of knowledge for layer-aware ranking */\nexport type KnowledgeLayer = 'project-truth' | 'promoted' | 'evidence';\n\n/** Document type discriminator for Orama index */\nexport type DocumentType = 'observation' | 'mini-skill';\n\n// ============================================================\n// Typed Memory Reference — Phase 3a reference protocol\n// ============================================================\n\n/** A typed reference to a memory object (observation or mini-skill) */\nexport interface MemoryRef {\n  kind: 'obs' | 'skill';\n  id: number;\n  projectId?: string;\n}\n\n/** MCP config format adapter interface */\nexport interface MCPConfigAdapter {\n  readonly source: AgentTarget;\n  /** Parse MCP server entries from a config file */\n  parse(content: string): MCPServerEntry[];\n  /** Generate config file content from MCP server entries */\n  generate(servers: MCPServerEntry[]): string;\n  /** Get the default config file path for this agent */\n  getConfigPath(projectRoot?: string): string;\n}\n"],"mappings":";AAsEO,IAAM,oBAAqD;AAAA,EAChE,mBAAmB;AAAA,EACnB,UAAU;AAAA,EACV,oBAAoB;AAAA,EACpB,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,aAAa;AAAA,EACb,iBAAiB;AAAA,EACjB,YAAY;AAAA,EACZ,aAAa;AAAA,EACb,aAAa;AAAA,EACb,SAAS;AACX;AAoLO,IAAM,qBAA+C;AAAA,EAC1D,gBAAgB,CAAC,gBAAgB,UAAU,OAAO,aAAa,SAAS;AAAA,EACxE,OAAO,CAAC,UAAU,OAAO,SAAS,cAAc,SAAS,kBAAkB;AAAA,EAC3E,YAAY,CAAC,YAAY,aAAa,UAAU,UAAU;AAAA,EAC1D,UAAU,CAAC,UAAU,SAAS,OAAO,eAAe,YAAY;AAAA,EAChE,aAAa,CAAC,aAAa,YAAY,WAAW,QAAQ;AAAA,EAC1D,WAAW,CAAC,WAAW,cAAc,YAAY,eAAe;AAClE;AAoJO,IAAM,iBAAyC;AAAA,EACpD,kBAAkB;AAAA,EAClB,iBAAiB;AAAA,EACjB,gBAAgB;AAClB;","names":[]}

package/docs/1.2.2-MEMORY-CONTROL-PLANE.md

@@ -0,0 +1,434 @@
+# Memorix 1.2.2 Memory Control Plane
+
+Status: active development
+Branch: `codex/1.2.2-memory-control-plane`
+Baseline: `memorix@1.2.1`, tag `v1.2.1`
+Start: 2026-07-24
+
+## Product Promise
+
+Memorix 1.2.1 can already build a bounded task Workset from code state, Git
+facts, durable memories, claims, wiki pages, workflows, and verification
+hints. 1.2.2 makes that useful behavior consistent across the product.
+
+For a normal agent request such as "continue the login timeout fix", the agent
+should not need to remember a Memorix command or understand storage layers.
+When Memorix has useful evidence, it should quietly deliver a short, current,
+source-backed brief. When it does not, it should stay small and let the agent
+read the code normally.
+
+This is a control-plane release, not a new collection of memory types. Its job
+is to make existing evidence flow through one controlled path:
+
+```text
+capture -> qualify -> maintain -> assemble -> deliver -> receipt -> improve
+```
+
+The result must be less prompt ballast, not more.
+
+## Why This Release Exists
+
+The 1.2.1 foundation is real, but it has three seams that matter to users:
+
+1. `TaskWorkset` has a budget and provenance, while session handoff and legacy
+   graph-context paths can still form their own output outside the same
+   admission and receipt rules.
+2. A previous-session summary is valuable for a handoff, but a raw summary or
+   a scan of every active observation is unsafe to inject at SessionStart. It
+   can be slow, noisy, and consume the next agent's limited attention.
+3. Memory retention, consolidation, claims, workspace compilation, and
+   background jobs exist, but the product does not yet expose one answer to
+   "why was this included, why was this withheld, and what will be refreshed?"
+
+The open embedding request also identifies a separate boundary: Memorix needs
+a provider capability contract before it can honestly support query/document
+intent or media inputs. Text-only OpenRouter embedding remains the supported
+default until a capability is implemented end to end.
+
+## Existing Foundations To Reuse
+
+- `TaskWorkset` and the bounded Workset renderer in `src/knowledge/workset.ts`.
+- Auto Project Context and Context Pack adapters in `src/codegraph`.
+- Code State snapshots, Claim Ledger, Knowledge Workspace, canonical workflows,
+  evaluation fixtures, and durable maintenance jobs from 1.2.1.
+- Existing retention, deduplication, consolidation, and secret filtering.
+- The `micro` MCP profile. It remains the normal coding-agent surface; 1.2.2
+  must not answer an internal architecture problem by adding more default tools.
+
+## What To Borrow From AgentMemory
+
+AgentMemory is a useful reference implementation, not a template to copy. Its
+[architecture guide](https://github.com/rohitg00/agentmemory/blob/main/plugin/skills/agentmemory-architecture/SKILL.md),
+[context function](https://github.com/rohitg00/agentmemory/blob/main/src/functions/context.ts),
+and [hybrid search](https://github.com/rohitg00/agentmemory/blob/main/src/state/hybrid-search.ts)
+show a coherent capture, compression, lifecycle, and retrieval system.
+
+The parts worth adopting are product disciplines:
+
+| AgentMemory pattern | Memorix adoption | Important adaptation |
+| --- | --- | --- |
+| Automatic hook capture | Keep capture effortless, but record a small event/evidence record first. | Reading a file, repeated shell output, or agent chatter is not durable project knowledge by default. |
+| Raw observation, compressed fact, session summary, lesson/profile layers | Make evidence stages explicit: ephemeral event -> candidate -> qualified durable memory/claim -> reviewable wiki/workflow artifact. | Do not create a second opaque transcript database. Existing observations and source refs remain the base. |
+| Decay, access tracking, consolidation, forget | Apply lifecycle policy by evidence kind and source validity. | A code fact becomes suspect when its source changes; a release decision is superseded by evidence, not merely aged out. |
+| BM25 + vector + graph RRF | Use multiple retrieval lanes and bounded fusion. | Code State is a currentness gate, not one more fuzzy graph score. Task lens and provenance must outrank generic recency. |
+| Agent id and fail-closed isolated scope | Add uniform actor/source/visibility policy to every automatic write and delivery path. | Project facts can be shared deliberately; personal notes and private handoffs never leak because an agent id was absent. |
+
+The resulting Memorix lifecycle is intentionally narrower than "remember
+everything":
+
+```text
+Ephemeral event/evidence
+  -> candidate (deduplicated, sanitized, not injected)
+  -> qualified durable memory or claim (source-backed, task-addressable)
+  -> approved knowledge/workflow artifact (reviewable)
+  -> temporary TaskWorkset or HandoffPacket (bounded delivery only)
+```
+
+This is not a new storage stack. The first implementation adds lifecycle and
+provenance semantics to existing observations, claims, sessions, and
+maintenance jobs before considering any new table.
+
+AgentMemory's retrieval and delivery paths are also deliberately separated in
+its implementation: its hybrid search uses BM25, vector, and graph signals,
+while its automatic context builder assembles profile/lesson/recent-session
+blocks under a token budget. Memorix should keep that separation but improve
+the final choice: task relevance, current code state, source confidence, and
+workflow applicability must decide delivery. Recent text is a tie-breaker, not
+the primary truth signal.
+
+## Non-Negotiable Invariants
+
+- **Current source wins.** Historical text, handoffs, derived claims, and
+  external code intelligence are evidence, never executable instruction.
+- **Every automatic delivery has a budget.** Context is selected as whole,
+  traceable items. It is not cut from an arbitrary raw corpus.
+- **No foreground corpus work.** MCP initialize, tools/list, SessionStart, and
+  Project Context may schedule maintenance, but do not wait for a broad scan,
+  model call, or remote embedding request.
+- **Silence is a valid result.** When evidence has no material advantage for
+  the task, Memorix returns a compact cold/fresh-project result instead of
+  manufacturing a narrative.
+- **Historical content is untrusted.** Injected handoffs and stored text are
+  clearly delimited as historical evidence and cannot override host or project
+  instructions.
+- **Source and recipient are explicit.** Every selected item carries source
+  references, freshness/trust state, selection reason, and a target surface.
+- **One model/vector family is one index identity.** Changing provider, model,
+  dimensions, modality, or embedding intent never mixes incompatible vectors;
+  it requires an explicit reindex policy.
+- **No automatic project writes.** Wiki/workflow proposals and agent adapters
+  remain reviewable. 1.2.2 does not mutate users' global agent configuration
+  to make an integration work.
+
+## Control-Plane Contract
+
+`TaskWorkset` remains the public task-shaped result. 1.2.2 introduces a
+shared internal assembly contract rather than a competing memory store:
+
+```text
+ContextCandidate
+  id / kind                 handoff, current-fact, code-state, claim,
+                            knowledge-page, workflow, verification, caution
+  sourceRefs / sourceHash
+  trust                     source-backed, derived, historical
+  freshness                 current, suspect, stale, unknown
+  relevance / importance
+  estimatedTokens
+  delivery                  task, hook-handoff, explicit-pull
+
+ContextAssembly
+  task / target surface / budget
+  selected candidates / omitted candidates with reasons
+  cautions / refresh actions
+  receipt
+```
+
+The Workset renderer, compact SessionStart handoff, Context Pack, and legacy
+graph-summary compatibility path must become views of this contract. They may
+have different budgets, but not different safety rules.
+
+The receipt is privacy-safe metadata, not another prompt section. It records
+at least selected source kinds and ids, reason, freshness, token counts,
+omissions, truncation, scheduled refreshes, and elapsed assembly time. It must
+not contain credentials, raw private source, or signed URLs.
+
+## Delivery Phases
+
+### Phase 0: Baseline And Failure Fixtures
+
+Record the present behavior before changing it. Add deterministic fixtures for:
+
+- a fresh project with no useful history;
+- a mature project with many active observations;
+- a long previous-session summary containing a secret-shaped value;
+- a stale/dirty/incomplete Code State result;
+- multiple workflows where generic words such as "verify" must not select the
+  release workflow;
+- an unavailable embedding provider and a changed vector identity.
+
+The fixtures measure output budget, selected evidence, omissions, and whether
+the foreground path scheduled rather than awaited maintenance. No performance
+number is claimed before it is measured on the supported Windows setup.
+
+### Phase 1: Shared Context Assembly
+
+Build the small `ContextCandidate` and `ContextAssembly` core around the
+existing Workset selector. Route Auto Project Context, Context Pack, and
+hook-delivered context through it without changing the default MCP profile.
+
+Acceptance gate:
+
+- same evidence produces stable selected/omitted reasons across each surface;
+- every rendered result remains inside its surface budget;
+- legacy prompt and JSON compatibility remain intact where documented;
+- an empty or irrelevant memory corpus produces a small answer;
+- `memorix explain` and JSON consumers can inspect a receipt without reading
+  storage internals.
+
+### Phase 2: Compact, Safe Session Handoff
+
+Introduce a dedicated `HandoffPacket`, not a call to the old broad
+`getSessionContext()` formatter. It reads the most recent eligible completed
+session and a bounded set of task-relevant durable evidence. Storage and
+delivery both have explicit character/token limits, redaction, a truncation
+marker, and a strict time budget.
+
+Full session history remains an explicit pull through the existing session
+surface. SessionStart only receives the small historical packet when the
+project's behavior setting enables it and the packet earns delivery.
+
+Acceptance gate:
+
+- `minimal + handoff`, `full + handoff`, disabled, and `silent` behavior have
+  positive hook integration coverage;
+- large summaries cannot block startup or exceed the injection budget;
+- config resolves from the hook input project root, never accidental process
+  cwd;
+- historical packet delimiters and redaction are visible in host output;
+- users can inspect a receipt and explicitly pull the full context.
+
+### Phase 3: Admission, Lifecycle, And Refresh Discipline
+
+Make the control loop decide what becomes durable evidence and what stays
+ephemeral activity. Reuse existing retention and consolidation logic, but make
+admission state, conflicts, requalification, maintenance actions, and reasons
+visible to the assembly layer.
+
+Start with a conservative automatic-write policy:
+
+- explicit user/agent saves, Git facts, focused test outcomes, verified tool
+  failures, and source-linked decisions can become candidates;
+- repeated reads, routine successful commands, raw conversation filler, and
+  unqualified tool output stay ephemeral or are dropped;
+- background consolidation may summarize compatible candidates, but it never
+  promotes them into an approved claim without provenance and policy;
+- every automatically captured record carries capture path, actor/session,
+  project, source reference, and visibility (`personal`, `project`, or `team`)
+  before it can be retrieved by another agent.
+
+The initial multi-agent read policy is fail-closed for private scopes. A
+missing actor id must not silently mean "read every agent's handoff". Project
+shared evidence remains possible only through an explicit project visibility
+rule and keeps the original actor in its receipt.
+
+Acceptance gate:
+
+- repeated low-value hook activity does not crowd out source-backed decisions;
+- changed/deleted code downgrades related evidence deterministically;
+- duplicate lifecycle signals enqueue one recoverable job;
+- failed or deferred maintenance appears as a concise caution/receipt, not a
+  blocking foreground error;
+- consolidation never destroys a source reference needed for drill-down;
+- a private handoff cannot cross an agent boundary without an explicit shared
+  visibility rule, while project-level verified facts remain available to the
+  agents that need them.
+
+### Phase 3 Implementation Status: Admission And Qualification
+
+The first Phase 3 slice is implemented. It adds a small admission state to the
+existing observation record instead of creating a second transcript store:
+
+| State | Meaning | Automatic delivery |
+| --- | --- | --- |
+| `ephemeral` | Routine automatic activity retained only as a short-lived trace. | Never selected. |
+| `candidate` | Sanitized automatic evidence worth retaining, but not yet current/source-backed. | Never selected. |
+| `qualified` | A candidate that a Code Memory scan completed after capture and linked to one or more current code references. | Eligible, subject to ordinary task relevance and budget. |
+
+Automatic hooks and orchestration writes now use this policy. File mutations,
+concrete failures, decisions, verified fixes, and pipeline summaries start as
+`candidate`; routine command success and task-completion telemetry are
+`ephemeral`; low-signal activity is dropped. Automatic capture is silent in
+the host agent rather than adding a stream of "saved memory" status messages.
+
+`observation-qualify` is a deduplicated maintenance job. It runs only after a
+CodeGraph refresh, rejects a snapshot older than the capture, binds the
+observation to the current scan, and upgrades only candidates with current
+code references. It never creates a Claim; claim derivation remains limited to
+explicit saves and Git evidence.
+
+The real hook path persists a candidate before it schedules Code Memory work,
+so a fast background worker cannot scan an earlier project state and strand a
+new candidate. CLI, hook, and foreground-refresh paths register their local
+project target before they enqueue isolated maintenance, letting the control
+plane locate the correct project root without placing a path in an MCP job
+payload.
+
+Auto Project Context, automatic session L1 context, Wiki/Knowledge Graph
+compilation, and graph-context packets exclude `candidate` and `ephemeral`
+records. Explicit retrieval still permits inspection, while ordinary search
+prefers qualified material and falls back only when no qualified result exists.
+
+Pending candidates are deliberately excluded from automatic consolidation so
+their evidence grain remains inspectable.
+
+### Phase 3 Implementation Status: Actor And Visibility Boundaries
+
+The second Phase 3 slice gives the existing observation record a small,
+uniform access policy instead of creating a parallel private-memory store:
+
+| Visibility | Reader rule | Write rule |
+| --- | --- | --- |
+| `project` | Any caller bound to that project. This is also the legacy default. | A caller bound to that project. |
+| `team` | An active coordination member of that project. | An active coordination member of that project. |
+| `personal` | The creator or an explicit recipient in that project. | The creator only. |
+
+SQLite and Orama retain the visibility, creator, and explicit recipient list.
+Records created before this control-plane slice remain `project` visible so an
+upgrade cannot hide existing project knowledge. Automatic hook and
+orchestrator traces begin personal; only a later source-backed qualification
+may promote a hook record to project evidence. A targeted handoff is personal
+to its sender and recipient, while an untargeted handoff is team-visible.
+Automatic orchestration lesson retrieval is an unbound project reader, so it
+cannot inject personal or team-scoped records into another agent's prompt.
+
+The same reader policy is applied to MCP search/detail/timeline/context,
+automatic context, session packets, the regular CLI and TUI, both dashboards,
+knowledge compilation, graph context, retention, consolidation, and scoped
+maintenance. A recipient may read a targeted handoff but cannot mutate it.
+Topic-key upserts check write scope before a write, so guessing a private key
+does not disclose or modify the record. The project-attribution guard also
+receives only records visible to the current reader.
+
+The embedded SDK remains an unbound project-visible reader. The CLI and local
+TUI also default to that reader, but an operator may explicitly select an
+active local identity with `memorix identity join|use` or one command of
+`--as <agent-id>`. That identity receives only its own personal/team access;
+it does not turn the local database into ambient access to another agent's
+records. Clearing the identity returns the terminal to project scope. CLI and
+MCP transfer exports also use this reader, so an unbound backup cannot include
+personal/team observations merely because they share a project database.
+
+Explicit full-purge commands remain local operator maintenance commands behind
+their existing confirmations; they are intentionally outside ordinary agent
+delivery and mutation paths. Remaining Phase 3 work is limited to richer
+qualified-evidence consolidation, deterministic source-change demotion for
+non-code evidence, and receipt-level lifecycle cautions.
+
+### Phase 4: Embedding Capability Foundation
+
+Define provider capabilities before extending the public input surface:
+
+```text
+EmbeddingCapabilities
+  supportedModalities
+  supportedIntents
+  transport / endpoint family
+  maxInlineBytes / safe-reference policy
+  model / dimensions / vectorFamily
+  reindex requirement
+```
+
+The existing OpenRouter `qwen/qwen3-embedding-8b` text path remains unchanged
+and tested. Provider adapters must use their official protocol; a Google-native
+embedding request is not treated as a generic OpenAI `/embeddings` request.
+
+Media support only ships when an agent can safely complete the whole path:
+validated input -> durable provenance -> supported embedding/extraction ->
+index -> retrieval -> receipt. A typed internal foundation is allowed to land
+on its own only if its docs and issue linkage say exactly that; it cannot claim
+to close media retrieval before the end-to-end path exists.
+
+Acceptance gate:
+
+- capability and vector identity participate in cache/index identity;
+- unsupported modality/intent degrades predictably to lexical search with a
+  receipt rather than silently fabricating a vector;
+- reference validation rejects credentials in URLs and private, loopback,
+  link-local, and unsafe IPv6 targets, with DNS/rebinding policy documented;
+- provider request-shape tests derive from official contracts, not mocked
+  generic paths;
+- model/dimension/vector-family change requests or performs an explicit,
+  observable reindex.
+
+### Phase 5: Product Surface And Diagnostics
+
+Keep the normal interaction simple: a supported agent uses the user's task and
+gets Project Context when it helps. Operators can ask for a concise answer to
+"what did Memorix use?" through existing context/explain/doctor paths.
+
+Acceptance gate:
+
+- default tool count stays at the current micro profile level;
+- receipt explains inclusion, omission, freshness, and scheduled work in plain
+  language;
+- dashboard/CLI empty, unavailable, stale, and refresh-queued states are
+  distinguishable;
+- user-facing docs do not call a deterministic memory map a semantic graph or
+  describe a provider foundation as full multimodal retrieval.
+
+### Phase 6: Evaluation, Contribution Review, And Release
+
+Run the existing Workset evaluation harness plus new control-plane fixtures,
+full test/build/lint, package inspection, isolated Windows install, stdio MCP
+smoke, and supported-agent integration smoke. Release evidence must include
+the new budgets and no-foreground-wait behavior.
+
+## Open Contributions And Issue Boundaries
+
+### #135: Session Handoff
+
+The contributor identified the right product gap. Their branch remains the
+authoritative contribution and is invited to revise against Phase 2. It can be
+merged with full contributor credit when it uses the bounded handoff contract,
+target-project config resolution, explicit historical-data delimiters, and
+positive E2E coverage. Memorix will not reimplement it privately and label it
+as original work.
+
+### #133 / #134: Multimodal Embedding Inputs
+
+The contributor's typed input and cache-identity direction is useful. The PR
+cannot close #133 in its current form because its Google routing is not the
+official native protocol, safe URL storage is incomplete, and no MCP media
+input reaches index/retrieval. The contributor can either complete the
+end-to-end path or narrow the PR to a validated capability foundation; both
+remain eligible for review and credit. This phase deliberately separates that
+work from an unsupported promise of "any media in, semantic memory out".
+
+### #136: MemorixBench-Transfer
+
+The research artifact stays a draft research track. It is not bundled into a
+product patch merely because its CI is green.
+
+## Explicit Non-Goals
+
+- Capture every conversation, terminal output, or hook event by default.
+- Invent a 53-tool management surface to expose internal machinery.
+- Let a session handoff override project instructions or current code.
+- Claim universal multimodal embedding through one OpenAI-compatible endpoint.
+- Merge unrelated historical PRs or rewrite contributor work without credit.
+- Turn Memorix into a cloud knowledge graph service; local-first evidence and
+optional project artifacts remain the product boundary.
+
+## Definition Of Done
+
+1. All automatic context surfaces use the shared assembly/receipt policy.
+2. Session handoff is bounded, redacted, project-root-correct, and proven by
+   hook E2E tests.
+3. Lifecycle decisions can be explained and foreground requests do not await
+   corpus maintenance.
+4. Embedding capabilities make text behavior honest and leave no false media
+   retrieval claim.
+5. Existing MCP clients retain a compact default profile and documented
+   compatibility.
+6. Evaluation, clean-package smoke, supported-agent smoke, docs, changelog,
+   tag, npm package, and release evidence agree before publication.

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -54,6 +54,10 @@ For direct use, prefer `memorix ...` commands first. In the 1.2 line, the CLI co
 
 Do not ask memory-only users to join coordination state. A lightweight session is enough for memory, retrieval, reasoning, and continuation. Use `joinTeam` / `team_manage(join)` only for explicit task/message/lock coordination or for CLI-agent work managed by `memorix orchestrate`.
 
+An unbound terminal is intentionally project-scoped: it reads and writes project-visible memory only. Use `memorix identity join --agent-type <agent>` or `memorix identity use --agent-id <id>` only when an operator explicitly needs personal/team memory or coordinated task actions. `memorix identity clear` removes that local selection; `--as <agent-id>` is the one-command script form and still requires an active member of the current project.
+
+`--cwd <git-project>` is the canonical way to run direct CLI work from outside a repository. It changes the command's project anchor only; Git remains the source of truth for final project identity.
+
 Use MCP when:
 
 - an IDE or agent needs tool calls