memorix 1.2.3 → 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.4-PERSISTENT-MEMORY-DELIVERY.md

@@ -0,0 +1,86 @@
+# 1.2.4 Persistent Memory Delivery
+
+**Status:** release-ready
+**Date:** 2026-07-26
+
+## Problem
+
+Memorix already has durable project memory, Code State, session summaries,
+knowledge, visibility policy, CLI, and MCP. The delivery path was uneven:
+
+- A fresh agent without a visible MCP tool could guess through many CLI commands
+  before finding the relevant state.
+- The normal task Workset deliberately avoided generic old-chat dumping, but it
+  also hid the small amount of prior work that matters when a user says
+  "continue" or "take over".
+- A new retrieval path must not bypass the session visibility fix shipped in
+  1.2.3.
+
+This release improves delivery, not storage. It does not create a handoff
+database, a transcript archive, or another default MCP tool.
+
+## Product Contract
+
+| Situation | Delivery |
+| --- | --- |
+| Start a new, unrelated task | A bounded task Workset. No automatic prior-session text. |
+| Continue or take over prior work | The same Workset plus a bounded prior-work projection. |
+| MCP is available | Use the existing `memorix_project_context` tool with the real task. |
+| MCP is unavailable | Make one CLI call: `memorix resume "<task>" --json` for continuation or `memorix context "<task>" --json` for a new task. |
+| Claude Code hook is installed | An explicit continuation prompt receives the same bounded prior-work Workset through the official `UserPromptSubmit` context channel, unless `memory.inject = "silent"`. |
+| Read-only assessment | The brief may be read, but Memorix does not persist a new observation unless the user explicitly asks to save one. |
+| Need a deliberate session handoff | Keep using the explicit session/handoff surfaces; this projection does not replace them. |
+
+Continuation detection is independent of the underlying task lens. For example,
+"continue fixing the authentication timeout" is still a `bugfix` task, with
+bugfix verification guidance, plus bounded prior-work evidence.
+
+## Delivery Model
+
+```text
+Canonical project identity
+  -> existing SQLite sessions + durable observations + visibility policy
+  -> Task Workset
+       -> normal task: current facts, code state, selected evidence
+       -> continuation: normal task + one session summary + <=3 durable anchors
+  -> existing MCP Project Context, direct CLI Context/Resume, or an eligible host hook
+```
+
+The projection is intentionally small and source-aware:
+
+- The latest meaningful completed session summary is eligible.
+- At most three durable decision/fix/discovery-style observations are eligible.
+- Project, team, and personal visibility is enforced with the caller's reader.
+- The `ContextReceipt` records selected or budget-withheld continuation items.
+- Current code remains the authority; historical material is a lead, not an
+  instruction.
+
+## Explicit Non-Goals
+
+- Do not inject arbitrary transcript history into every request.
+- Do not infer continuation from every mention of a past file or release.
+- Do not add a separate `handoff` store or duplicate session memory.
+- Do not add an eighth default MCP tool merely for CLI parity.
+- Do not make an unbound terminal see personal or team-scoped memory.
+
+## Acceptance Gates
+
+1. A normal new task has no `Resume from prior work` section.
+2. A continuation task has a bounded section and keeps its real task lens.
+3. `memorix resume` and `memorix_project_context` share the Workset contract.
+4. A foreign identity cannot receive personal continuation evidence.
+5. Generated guidance performs one precise CLI fallback instead of help/search
+   enumeration or inferring an empty memory store from project files.
+6. Compiled package smoke proves CLI positional parsing and stdio MCP output.
+7. Claude Code receives an explicit continuation through its official
+   `UserPromptSubmit.additionalContext` path; an unrelated prompt stays quiet.
+8. A fresh agent-style user path evaluates the installed package without
+   modifying the maintainer's real agent configuration.
+9. A fresh package installation whose optional native SQLite binary cannot load
+   still preserves the same `memorix.db` across separate CLI and hook processes
+   through the supported Node 22 SQLite fallback.
+10. A successful Autopilot brief preserves the exact continuation flag/path or
+    command needed to act, and does not trigger redundant memory retrieval by
+    default.
+11. A read-only continuation assessment neither replays already-delivered
+    durable evidence nor writes a new memory without an explicit user request.

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/AGENT_OPERATOR_PLAYBOOK.md

@@ -38,7 +38,7 @@ For the 1.2 release line, the visible product shape is:
 - model lanes are separate: `[memory.llm]` for formation/rerank/summaries, `[embedding]` for semantic search, `[agent]` for the model memcode talks to while coding
 - legacy `memorix.yml`, `.env`, and `~/.memorix/config.json` are compatibility inputs, not the recommended setup path
 - generated agent rules treat `memorix_session_start` as optional unless explicit session semantics matter
-- `memorix_project_context` / `memorix context --task "..."` is the normal black-box entry for non-trivial coding work: it assembles a bounded task Workset instead of injecting a generic memory dump
+- `memorix_project_context` / `memorix context "..."` is the normal black-box entry for non-trivial coding work: it assembles a bounded task Workset instead of injecting a generic memory dump; `memorix resume "..."` is the explicit CLI continuation projection
 - Code State keeps local snapshots and freshness links; a healthy pre-existing local CodeGraph index can add a bounded semantic outline, but Memorix never initializes or synchronizes that external index itself
 - `memorix knowledge` is an explicit review path for source-backed Markdown knowledge and canonical workflows. Do not initialize a versioned workspace or apply a proposal unless the user asks for that managed artifact
 - integration surfaces are agent-specific: Claude Code, Codex, GitHub Copilot CLI, Antigravity, and Hermes receive plugin packages; OpenClaw receives a compatible bundle; Pi and Oh-my-Pi receive package entries; Gemini CLI receives an extension package; OpenCode receives a plugin file and skill; Cursor and other agents receive MCP/rules/hooks where supported
@@ -766,6 +766,18 @@ memorix doctor
 
 to inspect active runtime status.
 
+### 9. Does a fresh CLI install report a `better-sqlite3` binding error?
+
+On the supported Node 22 runtime, current Memorix releases automatically use
+Node's built-in SQLite with the same local `memorix.db` when the optional
+`better-sqlite3` native binary is unavailable. Upgrade the package and rerun
+the command; do not delete the data directory or create a replacement database.
+
+Node may print its own experimental SQLite warning on that fallback path. It is
+not a memory-loss condition. If Memorix instead reports that SQLite is
+unavailable, confirm the installed Node version satisfies the package engine
+and include the exact error when filing an issue.
+
 ---
 
 ## 11. What Not to Do

package/docs/API_REFERENCE.md

@@ -59,7 +59,7 @@ The current CLI namespaces are:
 Typical examples:
 
 ```bash
-memorix --cwd /path/to/repo context --task "continue auth bug"
+memorix --cwd /path/to/repo resume "continue auth bug"
 memorix identity join --agent-type codex --name codex-main
 memorix session start --agent codex-main --agent-type codex --join-team --use
 memorix memory search --query "release blocker"
@@ -96,6 +96,8 @@ memorix codegraph status
 memorix codegraph status --json
 memorix context
 memorix context --task "continue auth bug"
+memorix context "continue auth bug"
+memorix resume "continue auth bug"
 memorix context --task "prepare 1.1.7 release"
 memorix explain
 memorix codegraph context-pack --task "continue auth bug"
@@ -107,11 +109,11 @@ MCP:
 - `memorix_codegraph_status` returns provider/index counts for the current project.
 - `memorix_context_pack` builds a task-specific packet with reliable current memories, lower-trust unbound memories, current code facts, freshness warnings, suggested reads, and suggested verification.
 
-`memorix context` defaults to `--refresh auto`, so first use can seed Code State without a separate manual `memorix codegraph refresh`. Its brief puts live package/changelog/Git facts before memory hints and flags old `progress.txt` / dev-log notes as historical when they predate the latest changelog, so agents should treat current facts as the source of truth when files disagree. Task lenses keep the packet shaped to the work: bugfix briefs prefer failing tests and repros, release briefs prefer metadata/changelog/package checks, and onboarding briefs prefer docs and entry points while hiding unrelated suspect details. Use `--refresh never` for read-only inspection and `--refresh always` when you want to force a fresh scan.
+`memorix context` defaults to `--refresh auto`, so first use can seed Code State without a separate manual `memorix codegraph refresh`. Its brief puts live package/changelog/Git facts before memory hints and flags old `progress.txt` / dev-log notes as historical when they predate the latest changelog, so agents should treat current facts as the source of truth when files disagree. Task lenses keep the packet shaped to the work: bugfix briefs prefer failing tests and repros, release briefs prefer metadata/changelog/package checks, and onboarding briefs prefer docs and entry points while hiding unrelated suspect details. Continuation delivery is separate from the task lens: continuation language in `memorix_project_context` enables a bounded prior-work projection, and `memorix resume "..."` makes that choice explicit. It includes only the latest useful session summary and up to three readable durable memories; ordinary new tasks do not receive historical-session context. A completed MCP brief is the default retrieval boundary: search, detail, or Context Pack should expand it only for a named missing fact or an explicit request for deeper history. Use `--refresh never` for read-only inspection and `--refresh always` when you want to force a fresh scan.
 
 Project-specific generated, vendored, or cache paths can be excluded from Code State with `[codegraph].exclude_patterns` in `memorix.toml` or `~/.memorix/config.toml` (`codegraph.excludePatterns` in legacy YAML). User patterns extend the built-in excludes and are applied to indexing, Project Context suggested reads, and Context Pack suggested reads.
 
-SessionStart hooks keep the default minimal hint lightweight. When memory behavior is configured with `sessionInject=full`, Memorix injects the compact Memory Autopilot brief at session start instead of only listing recent text memories.
+SessionStart hooks keep the default minimal hint lightweight. When memory behavior is configured with `sessionInject=full`, Codex receives the compact Memory Autopilot brief at session start instead of only listing recent text memories. Claude Code delivers an explicit continuation through its official `UserPromptSubmit` context channel, so a user saying “continue” receives the bounded prior-work brief even under the default minimal setting. Set `memory.inject = "silent"` to disable automatic hook delivery.
 
 The intended loop for agents is: get the project brief when it helps, inspect the suggested current files, use stale or unbound memory only as a lead, store durable outcomes after the work changes the project, and resolve obsolete memories.
 
@@ -220,6 +222,10 @@ require a joined coordination identity; a personal record is readable only by
 its creator and explicitly named recipients. Supplying a `topicKey` never
 lets an agent overwrite a record outside its write scope.
 
+When the current Autopilot task is read-only or explicitly says not to modify
+files, `memorix_store` returns without writing. Use `overrideReadOnly: true`
+only when the user explicitly asks to preserve a record during that task.
+
 Example:
 
 ```json
@@ -252,6 +258,8 @@ Important inputs:
 - `since`
 - `until`
 - `maxTokens`
+- `purpose` when deliberately expanding beyond the current Autopilot brief
+- `force: true` only when the user explicitly asks to re-read a record already represented in that brief
 
 Typical uses:
 
@@ -281,6 +289,8 @@ Global example:
 
 Fetch full observation detail.
 
+After `memorix_project_context`, use `purpose` only for a named missing fact. Set `force: true` only when the user explicitly asks for the full underlying record already represented in the brief.
+
 Supports two modes:
 
 - `ids` for current-project observations

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,13 +4,79 @@
 > older notes when they conflict.
 
 ## Current State
-- Phase: 1.2.3 session-context visibility hotfix
-- Branch: `codex/1.2.3-session-visibility`
-- Last updated: 2026-07-25
-- Released baseline: `memorix@1.2.2`, tag `v1.2.2`, `origin/main` at
-  `2a7ebc7`.
-- Goal: close the agent-facing session-context visibility boundary before
-  further control-plane work.
+- 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
+  durable observations, not a second handoff database. `TaskWorkset` keeps its
+  task lens (`bugfix`, `feature`, and so on) while independently recognizing a
+  continuation request.
+- A continuation Workset includes at most the latest meaningful completed
+  session summary plus three readable durable memory anchors. Each item is
+  visible in the existing `ContextReceipt`; ordinary tasks do not receive it.
+- `memorix resume "<task>"` is the CLI-equivalent continuation entry. The
+  existing MCP `memorix_project_context` receives the same behavior from the
+  user's task text, so the micro MCP profile stays at seven tools.
+- Setup-generated rules now use a single fallback call when MCP is genuinely
+  unavailable: `memorix resume` for prior work or `memorix context` for new
+  work. They explicitly forbid help probing, command enumeration, and broad
+  search loops before the first brief.
+- The visibility reader is carried into continuation retrieval, preserving
+  project aliases while failing closed for other agents' personal memory.
+- Continuation text preserves whole technical identifiers instead of emitting a
+  misleading partial token. MCP Project Context also establishes a short-lived
+  delivery boundary: a follow-up search/detail request does not re-send an
+  already represented record unless the caller names a missing fact or the user
+  explicitly asks for the underlying detail.
+- A read-only or "do not modify files" Autopilot task blocks `memorix_store`
+  by default. The only override is an explicit user request to persist a
+  record, represented by `overrideReadOnly: true`.
+- A real Codex user-path smoke, in a fresh Git fixture seeded only through the
+  public CLI, made one natural-language continuation request. Codex received
+  the bounded brief, used one specific Context Pack expansion, was stopped
+  from re-reading already-covered memory, made no `memorix_store` write, and
+  returned the correct read-only next step.
+- Completed local gates: TypeScript check, production build, focused
+  continuation/hook/CLI regressions, and the full suite (`237` files / `2677`
+  tests). A fresh packed install with optional native dependencies omitted used
+  Node SQLite to persist the same `memorix.db`; CLI resume retained
+  `AUTH_REFRESH_V2`; the micro MCP package surface exposed exactly seven tools
+  and enforced duplicate-retrieval plus read-only-write boundaries; and an
+  isolated Codex global setup wrote/activated the versioned Personal-marketplace
+  plugin with the matching skill guidance. Pending release gates: CI and
+  publish.
 
 ## 1.2.3 Session Context Visibility Hotfix
 - A real installed-package CLI smoke found that a second coordination identity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.3",
+  "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.3",
+  "version": "1.2.5",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/src/cli/capability-map.ts

@@ -3,7 +3,7 @@ export const CLI_NATIVE_PARITY: Record<string, string> = Object.freeze({
   memorix_search: 'memorix memory search',
   memorix_detail: 'memorix memory detail',
   memorix_graph_context: 'memorix memory graph-context',
-  memorix_project_context: 'memorix context',
+  memorix_project_context: 'memorix context|resume',
   memorix_context_pack: 'memorix codegraph context-pack',
   memorix_codegraph_status: 'memorix codegraph status',
   memorix_knowledge: 'memorix knowledge init|status|compile|lint|apply|workflow',

package/src/cli/command-guide.ts

@@ -39,7 +39,10 @@ const GUIDES: Record<string, CliCommandGuide> = {
   },
   context: {
     summary: 'Build the bounded task Workset used to resume or begin real work.',
-    usage: ['memorix context --task "continue the release fix" [--refresh auto|always|never]'],
+    usage: [
+      'memorix context "continue the release fix" [--refresh auto|always|never]',
+      'memorix resume "continue the release fix" [--refresh auto|always|never]',
+    ],
   },
   explain: {
     summary: 'Show why a task context contains its current facts and memory evidence.',

package/src/cli/commands/agent-integrations.ts

@@ -776,7 +776,11 @@ function isCurrentGuidance(content: string): boolean {
   return (
     content.includes('Memory Autopilot') &&
     content.includes('Default first step for non-trivial coding work') &&
-    content.includes('memorix_project_context')
+    content.includes('memorix_project_context') &&
+    content.includes('memorix resume') &&
+    content.includes('Continuation fallback is mandatory') &&
+    content.includes('Do not call more Memorix retrieval tools') &&
+    content.includes('read-only work')
   );
 }
 

package/src/cli/commands/codegraph.ts

@@ -60,7 +60,7 @@ function formatUsageHint(): string {
     '  memorix codegraph status --json',
     '  memorix codegraph context-pack --task "continue auth bug"',
     '',
-    'Tip: use `memorix context --task "..."` for the default agent-ready project context.',
+    'Tip: use `memorix context "..."` for new work or `memorix resume "..."` for prior work.',
   ].join('\n');
 }