memorix 1.0.7 → 1.0.8

package/dist/types.d.ts

@@ -30,16 +30,16 @@ interface KnowledgeGraph {
  * Observation type classification using claude-mem's icon-based legend system.
  *
  * Icon mapping:
- * 🎯 session-request   — User's original goal
- * 🔴 gotcha            — Critical pitfall / trap
- * 🟡 problem-solution  — Bug fix or workaround
- * 🔵 how-it-works      — Technical explanation
- * 🟢 what-changed      — Code/architecture change
- * 🟣 discovery         — New learning or insight
- * 🟠 why-it-exists     — Design rationale
- * 🟤 decision          — Architecture decision
- * ⚖️ trade-off         — Deliberate compromise
- * 🧠 reasoning         — Why this approach was chosen (System 2 reasoning trace)
+ * [SESSION] session-request   — User's original goal
+ * [GOTCHA] gotcha            — Critical pitfall / trap
+ * [FIX] problem-solution  — Bug fix or workaround
+ * [INFO] how-it-works      — Technical explanation
+ * [CHANGE] what-changed      — Code/architecture change
+ * [DISCOVERY] discovery         — New learning or insight
+ * [WHY] why-it-exists     — Design rationale
+ * [DECISION] decision          — Architecture decision
+ * [TRADEOFF] trade-off         — Deliberate compromise
+ * [REASONING] reasoning         — Why this approach was chosen (System 2 reasoning trace)
  */
 type ObservationType = 'session-request' | 'gotcha' | 'problem-solution' | 'how-it-works' | 'what-changed' | 'discovery' | 'why-it-exists' | 'decision' | 'trade-off' | 'reasoning';
 /** Map from ObservationType to display icon */

package/dist/types.js

@@ -1,15 +1,15 @@
 // src/types.ts
 var OBSERVATION_ICONS = {
-  "session-request": "\u{1F3AF}",
-  "gotcha": "\u{1F534}",
-  "problem-solution": "\u{1F7E1}",
-  "how-it-works": "\u{1F535}",
-  "what-changed": "\u{1F7E2}",
-  "discovery": "\u{1F7E3}",
-  "why-it-exists": "\u{1F7E0}",
-  "decision": "\u{1F7E4}",
-  "trade-off": "\u2696\uFE0F",
-  "reasoning": "\u{1F9E0}"
+  "session-request": "[SESSION]",
+  "gotcha": "[GOTCHA]",
+  "problem-solution": "[FIX]",
+  "how-it-works": "[INFO]",
+  "what-changed": "[CHANGE]",
+  "discovery": "[DISCOVERY]",
+  "why-it-exists": "[WHY]",
+  "decision": "[DECISION]",
+  "trade-off": "[TRADEOFF]",
+  "reasoning": "[REASONING]"
 };
 var TOPIC_KEY_FAMILIES = {
   "architecture": ["architecture", "design", "adr", "structure", "pattern"],

package/dist/types.js.map

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