memorix 1.2.4 → 1.2.5

package/dist/types.d.ts

@@ -184,6 +184,8 @@ interface TimelineContext {
     before: IndexEntry[];
     after: IndexEntry[];
 }
+/** Retrieval work allowed for a search request. */
+type RetrievalQuality = 'fast' | 'balanced' | 'thorough';
 /** Search options for the compact engine */
 interface SearchOptions {
     query: string;
@@ -202,6 +204,11 @@ interface SearchOptions {
     trackAccess?: boolean;
     /** Internal reader context for agent-facing visibility filtering. */
     reader?: ObservationReader;
+    /**
+     * `fast` stays fully local, `balanced` (default) permits embeddings, and
+     * `thorough` explicitly permits optional LLM query rewrite and reranking.
+     */
+    quality?: RetrievalQuality;
 }
 /** Topic key family heuristics for suggesting stable topic keys */
 declare const TOPIC_KEY_FAMILIES: Record<string, string[]>;
@@ -446,4 +453,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 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 };
+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 RetrievalQuality, 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/**\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":[]}
+{"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/** Retrieval work allowed for a search request. */\nexport type RetrievalQuality = 'fast' | 'balanced' | 'thorough';\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   * `fast` stays fully local, `balanced` (default) permits embeddings, and\n   * `thorough` explicitly permits optional LLM query rewrite and reranking.\n   */\n  quality?: RetrievalQuality;\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;AA4LO,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.5-RETRIEVAL-PERFORMANCE.md

@@ -0,0 +1,85 @@
+# 1.2.5 Retrieval Performance and Reliability
+
+## Goal
+
+Make retrieval predictable for both people and agents:
+
+- a normal search must not wait on optional LLM work;
+- a finished search must not leave a timeout timer alive and delay CLI exit;
+- embedding credentials must not silently become LLM credentials;
+- measured performance claims must identify the exact runtime being measured.
+
+This release improves the existing local SQLite + in-process Orama design. It
+does not introduce a daemon-only retrieval path, a new vector database, or a
+cross-process shared Orama index.
+
+## Retrieval Profiles
+
+| Profile | Use case | Local retrieval | Embeddings | LLM query rewrite / rerank |
+| --- | --- | --- | --- | --- |
+| `fast` | Scripts, probes, latency-sensitive agents | Yes | No | No |
+| `balanced` (default) | Everyday memory search | Yes | When configured | No |
+| `thorough` | An explicit, higher-quality investigation | Yes | When configured | Yes, only with an explicit memory LLM lane |
+
+`fast` never makes a network request and uses non-fuzzy lexical matching without
+vector payloads or fuzzy typo expansion. `balanced` preserves semantic vector
+search, typo tolerance, and intent-aware ranking but keeps optional LLM
+enrichment out of the default critical path.
+`thorough` is opt-in because it can add provider latency and cost.
+
+The profile is available through the SDK, `memorix memory search --quality`,
+the top-level `memorix search --quality` shortcut, and the `memorix_search` MCP
+tool. Existing callers that omit it receive `balanced` behavior.
+
+## Configuration Lanes
+
+Memorix has separate agent, memory-LLM, and embedding lanes. In particular:
+
+- `OPENROUTER_API_KEY` remains a compatible fallback for an embedding endpoint
+  hosted by OpenRouter.
+- It is not a generic memory-LLM credential.
+- It may supply the memory-LLM key only when `[memory.llm] provider =
+  "openrouter"`, or that lane explicitly points at an OpenRouter base URL.
+
+This prevents an embedding-only configuration from unexpectedly enabling LLM
+query rewriting or reranking.
+
+## Timeout Contract
+
+Every timeout helper must clear its timer when the protected operation settles.
+That applies to embedding requests, LLM reranking, MCP tool budgets, and
+background maintenance. This prevents a completed CLI command from being kept
+alive solely by a timeout watchdog while preserving a real deadline for a
+genuinely stalled operation.
+
+Timeouts still bound callers; they do not cancel a provider request that lacks
+an abort signal. The caller receives the fallback/error immediately, while the
+underlying request is allowed to settle safely in the background.
+
+## Evidence Protocol
+
+`npm run benchmark:retrieval` measures hot, in-process lexical retrieval with
+embeddings and LLM work disabled. It reports index-build time plus separate
+p50/p95/p99 values for a specific lookup and a broad query over a deterministic
+synthetic corpus. The two query shapes are intentionally not averaged together.
+
+It is deliberately not an end-to-end CLI, MCP, remote embedding, or LLM
+benchmark. Those paths have different startup, IPC, network, and provider
+costs and must be reported separately.
+
+Example:
+
+```powershell
+npm run build
+npm run benchmark:retrieval -- --records 1000 --runs 100
+```
+
+## Verification Gates
+
+1. Focused timeout, config, semantic-search, CLI, SDK, and MCP tests pass.
+2. The packaged CLI smoke verifies `fast`, default `balanced`, and
+   `thorough` argument handling without changing stored data.
+3. The MCP smoke verifies the `quality` schema and confirms no completed
+   search leaves a watchdog timer behind.
+4. Benchmark output is retained as evidence with its mode and machine context,
+   never presented as a universal latency guarantee.

package/docs/PERFORMANCE.md

@@ -14,6 +14,24 @@ Memorix is designed to be light for everyday memory use and explicit about heavi
 
 The default memory path uses local SQLite as the canonical store and Orama for search/indexing. No cloud service is required.
 
+## Retrieval Profiles
+
+| Profile | Default? | Network work | Best fit |
+| --- | --- | --- | --- |
+| `fast` | No | Never | Scripts, probes, latency-sensitive agent steps |
+| `balanced` | Yes | Optional embedding only | Everyday search |
+| `thorough` | No | Optional embedding plus explicitly enabled memory LLM work | A deliberate deep investigation |
+
+Use `--quality fast|balanced|thorough` with `memorix memory search` or
+`memorix search`; the `memorix_search` MCP tool and SDK expose the same field.
+`fast` is fully local. `balanced` keeps optional LLM query rewriting and
+reranking out of the normal search path. `thorough` is opt-in because it can
+add provider latency and cost.
+
+`OPENROUTER_API_KEY` may provide an API key for an OpenRouter embedding endpoint.
+It does not enable the memory-LLM lane unless that lane explicitly selects
+OpenRouter through its provider or base URL.
+
 ## Interactive and Maintenance Boundaries
 
 MCP transport readiness is separate from full search-index readiness. The first
@@ -58,6 +76,8 @@ On the release development machine used for this check, the healthy HTTP service
 | `MEMORIX_LLM_API_KEY` / `OPENAI_API_KEY` | unset | Enable LLM-backed enrichment, extraction, rerank, or skill generation |
 | `MEMORIX_LLM_TIMEOUT_MS` | `30000` (30 s) | Bound a single LLM-backed extraction/resolve call |
 | `MEMORIX_RERANK_TIMEOUT_MS` | provider default | Bound slow LLM rerank calls |
+| `memorix memory search --quality fast` | n/a | Force a fully local retrieval path for a latency-sensitive call |
+| `npm run benchmark:retrieval -- --records 1000 --runs 100` | n/a | Reproduce hot in-process lexical retrieval latency; not an end-to-end claim |
 | `[codegraph].max_file_bytes` | `2097152` | Raise only when a large file is intentional source that should enter Code Memory |
 | `memorix retention status` | report only | Inspect whether memory growth needs cleanup |
 | `memorix retention archive` | explicit | Archive expired memories when the project gets noisy |
@@ -71,6 +91,7 @@ On the release development machine used for this check, the healthy HTTP service
 - For Docker, use it when you want a managed HTTP service. Do not use image size alone as the runtime memory estimate.
 - For orchestrated subagent work, expect CPU and disk activity proportional to the spawned agents and verification commands.
 - For release checks, measure build/test/pack separately from idle service cost.
+- When comparing retrieval latency, report cold CLI, warm in-process SDK, MCP/HTTP, remote embedding, and LLM-enhanced paths separately. They have materially different costs.
 - When Dashboard shows queued or failed maintenance work, inspect
   `/api/maintenance` on that local dashboard before assuming a Code Memory scan
   or lifecycle task completed.
@@ -79,7 +100,7 @@ On the release development machine used for this check, the healthy HTTP service
 
 These are not release blockers, but they are reasonable future improvements:
 
-- Add a lightweight benchmark command that reports startup time, index size, SQLite size, and search latency.
+- Extend the retrieval benchmark with separately labelled cold CLI, MCP, and remote-provider cases when a release needs those comparisons.
 - Add dashboard-side performance telemetry for API latency and payload sizes.
 - Document recommended retention schedules for large projects.
 - Evaluate a persistent cross-process retrieval index only as a major-version

package/docs/dev-log/progress.txt

@@ -4,14 +4,39 @@
 > older notes when they conflict.
 
 ## Current State
-- Phase: 1.2.4 persistent memory delivery release candidate
-- Branch: `codex/1.2.4-persistent-memory-delivery`
-- Last updated: 2026-07-26
-- Released baseline: `memorix@1.2.3`, tag `v1.2.3`, `origin/main` at
-  `03ceb6d`.
-- Goal: make the existing persistent memory layer deliver useful prior work
-  naturally across MCP and CLI without turning ordinary tasks into historical
-  context dumps.
+- Phase: 1.2.5 retrieval performance and reliability release candidate
+- Branch: `codex/1.2.5-retrieval-performance`
+- Last updated: 2026-07-27
+- Released baseline: `memorix@1.2.4`, tag `v1.2.4`, `origin/main` at
+  `24f3b9b`.
+- Goal: make ordinary retrieval deterministic and bounded without changing the
+  local SQLite + in-process Orama architecture.
+
+## 1.2.5 Retrieval Performance and Reliability
+- Retrieval now has three explicit profiles: `fast` is fully local, `balanced`
+  is the default vector-capable path without LLM query work, and `thorough`
+  explicitly opts into configured LLM query rewrite/reranking.
+- `OPENROUTER_API_KEY` remains an embedding fallback only. It activates the
+  memory LLM lane only when that lane explicitly names an OpenRouter provider
+  or base URL, preventing embedding-only configurations from adding hidden
+  network work to normal search.
+- Embedding, rerank, MCP search, and maintenance share one timeout helper that
+  clears watchdog timers after settlement. This removes the previously measured
+  avoidable CLI exit delay from a completed rerank path while preserving real
+  timeouts for stalled work.
+- Read-only memory CLI commands skip session-store and maintenance-target setup
+  while retaining the existing project/identity visibility boundary.
+- Local verification completed before release: TypeScript check; focused
+  timeout/config/search/CLI/SDK tests; a full serial suite that reached a
+  single stale Codex plugin-manifest version assertion, followed by its
+  dedicated passing recheck after the template was synced; production build;
+  package SDK benchmark; real CLI smoke; and an in-memory MCP client smoke
+  confirming `memorix_search.quality` and `fast` mode.
+- Current benchmark evidence on Windows/Node 22: a 1,000-record hot in-process
+  SDK lexical fixture measured specific lookup p50 44.603 ms / p95 96.085 ms
+  and broad-query p50 160.903 ms / p95 171.878 ms. This excludes CLI startup,
+  MCP transport, remote embeddings, and LLM work by design; the two query
+  shapes are reported separately rather than averaged into a marketing number.
 
 ## 1.2.4 Persistent Memory Delivery
 - Continuation is now a bounded delivery projection over existing sessions and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,
@@ -62,6 +62,7 @@
     "test:llm-live": "MEMORIX_RUN_LIVE_LLM_TESTS=1 vitest run tests/integration/formation-llm-quality.test.ts",
     "test:e2e": "vitest run tests/e2e/",
     "benchmark:codegraph": "node scripts/benchmark-codegraph-provider.cjs",
+    "benchmark:retrieval": "npm run build && node scripts/benchmark-retrieval.mjs",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build && npm test"
   },

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/src/cli/commands/memory.ts

@@ -7,8 +7,10 @@ import { canManageObservation, filterReadableObservations, resolveObservationVis
 import {
   coerceObservationStatus,
   coerceObservationType,
+  coerceRetrievalQuality,
   emitError,
   emitResult,
+  getCliReadContext,
   getCliProjectContext,
   parseCsvList,
   parsePositiveInt,
@@ -36,6 +38,7 @@ export default defineCommand({
     topicKey: { type: 'string', description: 'Stable topic key override' },
     action: { type: 'string', description: 'Secondary action for advanced memory commands' },
     limit: { type: 'string', description: 'Limit for search/recent output' },
+    quality: { type: 'string', description: 'Retrieval profile: fast, balanced (default), or thorough' },
     graphLimit: { type: 'string', description: 'Limit for graph-context output' },
     graphQuery: { type: 'string', description: 'Query for graph-context packet' },
     format: { type: 'string', description: 'Output format for graph-context: summary or prompt' },
@@ -56,7 +59,12 @@ export default defineCommand({
     const asJson = !!args.json;
 
     try {
-      const { project, dataDir, reader, identity } = await getCliProjectContext({ searchIndex: true });
+      const readOnlyActions = new Set(['', 'search', 'graph-context', 'recent', 'suggest-topic-key', 'detail', 'timeline']);
+      const needsSearchIndex = action === 'search' || action === 'detail' || action === 'timeline';
+      const context = readOnlyActions.has(action)
+        ? await getCliReadContext({ searchIndex: needsSearchIndex })
+        : await getCliProjectContext({ searchIndex: true });
+      const { project, dataDir, reader, identity } = context;
 
       switch (action) {
         case 'search': {
@@ -66,7 +74,8 @@ export default defineCommand({
             return;
           }
           const limit = parsePositiveInt(args.limit as string | undefined, 10);
-          const result = await compactSearch({ query, limit, projectId: project.id, reader });
+          const quality = coerceRetrievalQuality(args.quality as string | undefined);
+          const result = await compactSearch({ query, limit, quality, projectId: project.id, reader });
           emitResult({ project, entries: result.entries }, result.formatted, asJson);
           return;
         }
@@ -420,7 +429,7 @@ export default defineCommand({
           console.log('Memorix Memory Commands');
           console.log('');
           console.log('Usage:');
-          console.log('  memorix memory search --query "timeout bug" [--limit 10]');
+          console.log('  memorix memory search --query "timeout bug" [--limit 10] [--quality fast|balanced|thorough]');
           console.log('  memorix memory recent [--limit 10]');
           console.log('  memorix memory store --text "..." [--title "..."] [--type discovery] [--visibility project|personal|team]');
           console.log('  memorix memory suggest-topic-key --type decision --title "..."');

package/src/cli/commands/operator-shared.ts

@@ -9,9 +9,10 @@ import type {
   ObservationStatus,
   ObservationType,
   ObservationVisibility,
+  RetrievalQuality,
 } from '../../types.js';
 import { getCliInvocation } from '../invocation.js';
-import { resolveCliIdentity, type CliIdentity } from '../identity.js';
+import { loadCliIdentity, resolveCliIdentity, type CliIdentity } from '../identity.js';
 
 export interface CliProjectContext {
   project: ProjectInfo;
@@ -22,7 +23,24 @@ export interface CliProjectContext {
   identityWarning?: string;
 }
 
-export async function getCliProjectContext(options?: { searchIndex?: boolean; projectRoot?: string }): Promise<CliProjectContext> {
+export interface CliReadContext {
+  project: ProjectInfo;
+  dataDir: string;
+  reader: ObservationReader;
+  identity: CliIdentity | null;
+  identityWarning?: string;
+}
+
+interface CliContextOptions {
+  searchIndex?: boolean;
+  projectRoot?: string;
+}
+
+async function resolveCliProjectContext(options?: CliContextOptions): Promise<{
+  project: ProjectInfo;
+  dataDir: string;
+  invocation: ReturnType<typeof getCliInvocation>;
+}> {
   const invocation = getCliInvocation();
   const detection = detectProjectWithDiagnostics(
     options?.projectRoot
@@ -37,6 +55,51 @@ export async function getCliProjectContext(options?: { searchIndex?: boolean; pr
 
   const project = detection.project;
   const dataDir = await getProjectDataDir(project.id);
+  return { project, dataDir, invocation };
+}
+
+/**
+ * Read-only memory commands do not need session bookkeeping or maintenance
+ * target registration. Identity resolution remains intact so visibility rules
+ * stay identical to the full operator context.
+ */
+export async function getCliReadContext(options?: CliContextOptions): Promise<CliReadContext> {
+  const { project, dataDir, invocation } = await resolveCliProjectContext(options);
+  await initObservations(dataDir);
+
+  if (options?.searchIndex) {
+    await prepareSearchIndex();
+  }
+
+  const storedIdentity = await loadCliIdentity(dataDir, project.id);
+  if (!invocation.actorId && !storedIdentity) {
+    return {
+      project,
+      dataDir,
+      reader: { projectId: project.id },
+      identity: null,
+    };
+  }
+
+  const teamStore = await initTeamStore(dataDir);
+  const identity = await resolveCliIdentity({
+    project,
+    dataDir,
+    teamStore,
+    explicitActorId: invocation.actorId,
+  });
+
+  return {
+    project,
+    dataDir,
+    reader: identity.reader,
+    identity: identity.identity,
+    ...(identity.warning ? { identityWarning: identity.warning } : {}),
+  };
+}
+
+export async function getCliProjectContext(options?: CliContextOptions): Promise<CliProjectContext> {
+  const { project, dataDir, invocation } = await resolveCliProjectContext(options);
   try {
     const { MaintenanceTargetStore } = await import('../../runtime/maintenance-targets.js');
     new MaintenanceTargetStore(dataDir).register({
@@ -129,6 +192,7 @@ const OBSERVATION_TYPES: ObservationType[] = [
 ];
 
 const OBSERVATION_STATUSES: ObservationStatus[] = ['active', 'resolved', 'archived'];
+const RETRIEVAL_QUALITIES: RetrievalQuality[] = ['fast', 'balanced', 'thorough'];
 
 export function coerceObservationType(input?: string): ObservationType {
   const normalized = (input ?? 'discovery') as ObservationType;
@@ -150,6 +214,14 @@ export function coerceObservationStatus(input?: string): ObservationStatus {
   return normalized;
 }
 
+export function coerceRetrievalQuality(input?: string): RetrievalQuality {
+  const normalized = (input ?? 'balanced').trim().toLowerCase() as RetrievalQuality;
+  if (!RETRIEVAL_QUALITIES.includes(normalized)) {
+    throw new Error('quality must be fast, balanced, or thorough');
+  }
+  return normalized;
+}
+
 export function coerceObservationVisibility(input?: string): ObservationVisibility {
   const normalized = (input ?? 'project').trim().toLowerCase();
   if (normalized === 'personal' || normalized === 'project' || normalized === 'team') {

package/src/cli/index.ts

@@ -985,12 +985,14 @@ const main = defineCommand({
       args: {
         query: { type: 'positional', description: 'Search query', required: true },
         limit: { type: 'string', description: 'Maximum results' },
+        quality: { type: 'string', description: 'Retrieval profile: fast, balanced (default), or thorough' },
         json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
       },
       async run({ args }) {
         await runMemoryShortcut('search', {
           query: args.query,
           limit: args.limit,
+          quality: args.quality,
           json: args.json,
         });
       },

package/src/config/resolved-config.ts

@@ -88,6 +88,27 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
   const legacy = loadFileConfig();
   const embeddingBaseUrl = first(process.env.MEMORIX_EMBEDDING_BASE_URL, toml.embedding?.base_url, yaml.embedding?.baseUrl, legacy.embeddingApi?.baseUrl);
   const openRouterEmbeddingApiKey = isOpenRouterUrl(embeddingBaseUrl) ? process.env.OPENROUTER_API_KEY : undefined;
+  const memoryLlmProvider = first(
+    process.env.MEMORIX_LLM_PROVIDER,
+    toml.memory?.llm?.provider,
+    yaml.llm?.provider,
+    legacy.llm?.provider,
+  );
+  const memoryLlmModel = first(
+    process.env.MEMORIX_LLM_MODEL,
+    toml.memory?.llm?.model,
+    yaml.llm?.model,
+    legacy.llm?.model,
+  );
+  const memoryLlmBaseUrl = first(
+    process.env.MEMORIX_LLM_BASE_URL,
+    toml.memory?.llm?.base_url,
+    yaml.llm?.baseUrl,
+    legacy.llm?.baseUrl,
+  );
+  const openRouterMemoryLlmApiKey = isOpenRouterMemoryLane(memoryLlmProvider, memoryLlmBaseUrl)
+    ? process.env.OPENROUTER_API_KEY
+    : undefined;
 
   const resolved: ResolvedMemorixConfig = {
     agent: {
@@ -126,9 +147,9 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
       autoCleanup: firstBool(toml.memory?.auto_cleanup, yaml.behavior?.autoCleanup),
       syncAdvisory: firstBool(toml.memory?.sync_advisory, yaml.behavior?.syncAdvisory),
       llm: {
-        provider: first(process.env.MEMORIX_LLM_PROVIDER, toml.memory?.llm?.provider, yaml.llm?.provider, legacy.llm?.provider),
-        model: first(process.env.MEMORIX_LLM_MODEL, toml.memory?.llm?.model, yaml.llm?.model, legacy.llm?.model),
-        baseUrl: first(process.env.MEMORIX_LLM_BASE_URL, toml.memory?.llm?.base_url, yaml.llm?.baseUrl, legacy.llm?.baseUrl),
+        provider: memoryLlmProvider,
+        model: memoryLlmModel,
+        baseUrl: memoryLlmBaseUrl,
         apiKey: first(
           process.env.MEMORIX_LLM_API_KEY,
           process.env.MEMORIX_API_KEY,
@@ -137,7 +158,7 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
           legacy.llm?.apiKey,
           process.env.OPENAI_API_KEY,
           process.env.ANTHROPIC_API_KEY,
-          process.env.OPENROUTER_API_KEY,
+          openRouterMemoryLlmApiKey,
         ),
       },
     },
@@ -290,6 +311,10 @@ function isOpenRouterUrl(value: string | undefined): boolean {
   }
 }
 
+function isOpenRouterMemoryLane(provider: string | undefined, baseUrl: string | undefined): boolean {
+  return provider?.trim().toLowerCase() === 'openrouter' || isOpenRouterUrl(baseUrl);
+}
+
 function normalizeExternalContext(value: string | undefined): 'auto' | 'off' | undefined {
   const normalized = value?.trim().toLowerCase();
   if (normalized === 'auto' || normalized === 'off') return normalized;

package/src/runtime/project-maintenance.ts

@@ -9,6 +9,7 @@ import {
   enqueueObservationQualification,
   type MaintenanceQueue,
 } from './lifecycle.js';
+import { withTimeout } from '../timeout.js';
 
 const DEFAULT_VECTOR_BATCH_SIZE = 12;
 const DEFAULT_RETENTION_BATCH_SIZE = 100;
@@ -110,20 +111,6 @@ async function loadWorkspaceForMaintenance(
   return versioned ?? local;
 }
 
-/**
- * Creates handlers for one initialized project runtime. The worker itself is
- * project-scoped so it never claims a different project's queued work.
- */
-function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-    promise.then(
-      (value) => { clearTimeout(timer); resolve(value); },
-      (error) => { clearTimeout(timer); reject(error); },
-    );
-  });
-}
-
 async function runAutomaticConsolidation(
   projectId: string,
   projectDir: string,

package/src/sdk.ts

@@ -26,6 +26,7 @@ import type {
   ProjectInfo,
   DetectionResult,
   ObservationReader,
+  RetrievalQuality,
 } from './types.js';
 import {
   canManageObservation,
@@ -90,6 +91,8 @@ export interface ClientSearchOptions {
   status?: ObservationStatus | 'all';
   /** Maximum results. Default: 20 */
   limit?: number;
+  /** Retrieval profile. Default: balanced. */
+  quality?: RetrievalQuality;
 }
 
 /** Result from resolving observations */
@@ -220,6 +223,7 @@ export class MemoryClient {
       type: options.type,
       source: options.source,
       status: options.status === 'all' ? undefined : (options.status ?? 'active'),
+      quality: options.quality,
       reader: this._reader,
     };