memorix 1.0.6 → 1.0.7

package/dist/types.d.ts

@@ -0,0 +1,396 @@
+/**
+ * Memorix Core Types
+ *
+ * Data model sources:
+ * - Entity/Relation/KnowledgeGraph: MCP Official Memory Server (v0.6.3)
+ * - Observation/ObservationType: claude-mem Progressive Disclosure
+ * - UnifiedRule/RuleSource: Memorix original (rules sync)
+ *
+ * Designed for extensibility: new agent formats (Kiro, Copilot, Antigravity)
+ * can be added by extending RuleSource and adding format adapters.
+ */
+/** A node in the knowledge graph representing a concept, component, or config */
+interface Entity {
+    name: string;
+    entityType: string;
+    observations: string[];
+}
+/** A directed edge between two entities */
+interface Relation {
+    from: string;
+    to: string;
+    relationType: string;
+}
+/** The complete knowledge graph */
+interface KnowledgeGraph {
+    entities: Entity[];
+    relations: Relation[];
+}
+/**
+ * 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)
+ */
+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 */
+declare const OBSERVATION_ICONS: Record<ObservationType, string>;
+/** Observation lifecycle status */
+type ObservationStatus = 'active' | 'resolved' | 'archived';
+/** Progress tracking for task/feature observations */
+interface ProgressInfo {
+    feature: string;
+    status: 'in-progress' | 'completed' | 'blocked';
+    completion?: number;
+}
+/** A rich observation record attached to an entity */
+interface Observation {
+    id: number;
+    entityName: string;
+    type: ObservationType;
+    title: string;
+    narrative: string;
+    facts: string[];
+    filesModified: string[];
+    concepts: string[];
+    tokens: number;
+    createdAt: string;
+    updatedAt?: string;
+    projectId: string;
+    /** Whether the observation contains causal language (because, due to, etc.) */
+    hasCausalLanguage?: boolean;
+    /** Optional topic key for upsert — same project+topicKey updates existing observation */
+    topicKey?: string;
+    /** How many times this observation was revised via topic key upsert (starts at 1) */
+    revisionCount?: number;
+    /** Session ID this observation belongs to */
+    sessionId?: string;
+    /** Lifecycle status: active (default) → resolved → archived */
+    status?: ObservationStatus;
+    /** ID of the observation that superseded this one (set when auto-resolved by topicKey upsert) */
+    supersededBy?: number;
+    /** Progress tracking for task/feature observations */
+    progress?: ProgressInfo;
+    /** Origin of this observation: agent (IDE hooks/MCP), git (commit ingest), manual (CLI) */
+    source?: 'agent' | 'git' | 'manual';
+    /** Git commit hash if source is 'git' */
+    commitHash?: string;
+    /** Related commit hashes — links reasoning memories to the commits they explain */
+    relatedCommits?: string[];
+    /** Related entity names — explicit cross-references to other memory entities */
+    relatedEntities?: string[];
+    /** Provenance detail: how this observation entered the system */
+    sourceDetail?: 'explicit' | 'hook' | 'git-ingest';
+    /** Value category from formation pipeline evaluation */
+    valueCategory?: 'core' | 'contextual' | 'ephemeral';
+    /** Phase 4a: Agent ID that created this observation (team attribution) */
+    createdByAgentId?: string;
+    /** Phase 4a: Monotonic write generation — snapshot of storage_generation at write time (watermark coherence) */
+    writeGeneration?: number;
+}
+/** A coding session tracked by Memorix */
+interface Session {
+    id: string;
+    projectId: string;
+    startedAt: string;
+    endedAt?: string;
+    summary?: string;
+    status: 'active' | 'completed';
+    /** Agent/IDE that started this session */
+    agent?: string;
+}
+/** L1 index entry — lightweight, ~50-100 tokens per result */
+interface IndexEntry {
+    id: number;
+    time: string;
+    type: ObservationType;
+    icon: string;
+    title: string;
+    tokens: number;
+    /** Relevance score from search (time-decayed). Used by compact engine. */
+    score?: number;
+    /** Project that owns this observation. Needed to disambiguate global results. */
+    projectId?: string;
+    /** Origin of the memory for source-aware retrieval and display. */
+    source?: 'agent' | 'git' | 'manual';
+    /** Provenance detail for source-aware display */
+    sourceDetail?: 'explicit' | 'hook' | 'git-ingest';
+    /** Value category for source-aware ranking */
+    valueCategory?: 'core' | 'contextual' | 'ephemeral';
+    /** Explainable recall: why this result matched. */
+    matchedFields?: string[];
+    /** Entity name — used for entity-affinity scoring and workstream deduplication. */
+    entityName?: string;
+    /** Document type: observation or mini-skill (Phase 3a) */
+    documentType?: DocumentType;
+    /** Knowledge layer for layer-aware ranking (Phase 3a) */
+    knowledgeLayer?: KnowledgeLayer;
+}
+/** Explicit reference to an observation, optionally scoped to a project. */
+interface ObservationRef {
+    id: number;
+    projectId?: string;
+}
+/** L2 timeline context — observations around an anchor */
+interface TimelineContext {
+    anchorId: number;
+    anchorEntry: IndexEntry | null;
+    before: IndexEntry[];
+    after: IndexEntry[];
+}
+/** Search options for the compact engine */
+interface SearchOptions {
+    query: string;
+    limit?: number;
+    type?: ObservationType;
+    projectId?: string;
+    since?: string;
+    until?: string;
+    /** Token budget — trim results to fit within this many tokens (0 = unlimited) */
+    maxTokens?: number;
+    /** Filter by observation status. Default: 'active' (only show active memories) */
+    status?: ObservationStatus | 'all';
+    /** Filter by observation source: 'agent', 'git', 'manual', or undefined for all */
+    source?: 'agent' | 'git' | 'manual';
+}
+/** Topic key family heuristics for suggesting stable topic keys */
+declare const TOPIC_KEY_FAMILIES: Record<string, string[]>;
+/** The document shape stored in Orama */
+interface MemorixDocument {
+    id: string;
+    observationId: number;
+    entityName: string;
+    type: string;
+    title: string;
+    narrative: string;
+    facts: string;
+    filesModified: string;
+    concepts: string;
+    tokens: number;
+    createdAt: string;
+    projectId: string;
+    /** Number of times this observation was returned in search results */
+    accessCount: number;
+    /** ISO timestamp of last access via search/detail */
+    lastAccessedAt: string;
+    /** Lifecycle status: active, resolved, archived */
+    status: string;
+    /** Origin: agent, git, manual */
+    source: string;
+    /** Provenance detail: explicit, hook, or git-ingest */
+    sourceDetail?: string;
+    /** Value category from formation evaluation */
+    valueCategory?: string;
+    /** Optional vector embedding for semantic/hybrid retrieval */
+    embedding?: number[];
+    /** Document type: observation or mini-skill (Phase 3a) */
+    documentType?: DocumentType;
+    /** Knowledge layer for layer-aware ranking (Phase 3a) */
+    knowledgeLayer?: KnowledgeLayer;
+}
+/**
+ * Supported agent/IDE rule sources.
+ * All 7 major AI IDEs are supported.
+ */
+type RuleSource = 'cursor' | 'claude-code' | 'codex' | 'windsurf' | 'antigravity' | 'gemini-cli' | 'copilot' | 'kiro' | 'trae' | 'memorix';
+/** A parsed rule in the unified intermediate representation */
+interface UnifiedRule {
+    id: string;
+    content: string;
+    description?: string;
+    source: RuleSource;
+    scope: 'global' | 'project' | 'path-specific';
+    paths?: string[];
+    alwaysApply?: boolean;
+    priority: number;
+    hash: string;
+}
+/**
+ * Format adapter interface — implement this for each agent/IDE.
+ * Adding a new agent (e.g., Kiro) only requires implementing this interface.
+ */
+interface RuleFormatAdapter {
+    /** Unique identifier for this agent format */
+    readonly source: RuleSource;
+    /** File paths/globs this adapter can parse */
+    readonly filePatterns: string[];
+    /** Parse rule files into unified representation */
+    parse(filePath: string, content: string): UnifiedRule[];
+    /** Generate rule file content from unified representation */
+    generate(rules: UnifiedRule[]): {
+        filePath: string;
+        content: string;
+    }[];
+}
+interface ProjectInfo {
+    id: string;
+    name: string;
+    gitRemote?: string;
+    rootPath: string;
+}
+/**
+ * Diagnostic failure info from project detection.
+ * Tells callers exactly WHY detection failed so they can report actionable errors.
+ */
+type DetectionFailureReason = 'path_not_found' | 'not_a_directory' | 'no_git' | 'git_worktree_error' | 'git_safe_directory' | 'remote_resolve_failed';
+interface DetectionFailure {
+    reason: DetectionFailureReason;
+    path: string;
+    detail: string;
+}
+interface DetectionResult {
+    project: ProjectInfo | null;
+    failure: DetectionFailure | null;
+}
+interface MemorixConfig {
+    dataDir: string;
+    projectId: string;
+    projectName: string;
+    enableEmbeddings: boolean;
+    enableRulesSync: boolean;
+    watchRuleFiles: boolean;
+}
+declare const DEFAULT_CONFIG: Partial<MemorixConfig>;
+/** Supported agent targets for workspace sync */
+type AgentTarget = 'windsurf' | 'cursor' | 'claude-code' | 'codex' | 'copilot' | 'antigravity' | 'gemini-cli' | 'kiro' | 'opencode' | 'trae';
+/** A unified MCP server entry across all agent config formats */
+interface MCPServerEntry {
+    name: string;
+    /** Command for stdio transport */
+    command: string;
+    /** Args for stdio transport */
+    args: string[];
+    /** Environment variables */
+    env?: Record<string, string> | null;
+    /** URL for HTTP/SSE transport (Codex uses `url`, Windsurf uses `serverUrl`) */
+    url?: string;
+    /** HTTP headers (Windsurf uses `headers` for HTTP transport) */
+    headers?: Record<string, string>;
+    /** Whether this server is disabled */
+    disabled?: boolean;
+}
+/** Unified workflow entry */
+interface WorkflowEntry {
+    name: string;
+    description: string;
+    content: string;
+    source: AgentTarget;
+    filePath: string;
+}
+/** A skill folder discovered from an agent's skills directory */
+interface SkillEntry {
+    name: string;
+    description: string;
+    sourcePath: string;
+    sourceAgent: AgentTarget;
+}
+/** Conflict when two agents have a skill with the same folder name */
+interface SkillConflict {
+    name: string;
+    kept: SkillEntry;
+    skipped: SkillEntry;
+}
+/** Result of a workspace sync operation */
+interface WorkspaceSyncResult {
+    mcpServers: {
+        scanned: MCPServerEntry[];
+        generated: {
+            filePath: string;
+            content: string;
+        }[];
+    };
+    workflows: {
+        scanned: WorkflowEntry[];
+        generated: {
+            filePath: string;
+            content: string;
+        }[];
+    };
+    rules: {
+        scanned: number;
+        generated: number;
+    };
+    skills: {
+        scanned: SkillEntry[];
+        conflicts: SkillConflict[];
+        copied: string[];
+        skipped: string[];
+    };
+}
+/** A mini-skill promoted from one or more observations */
+interface MiniSkill {
+    id: number;
+    /** Observation IDs this mini-skill was derived from (live refs, best-effort) */
+    sourceObservationIds: number[];
+    /** Entity the source observations belong to */
+    sourceEntity: string;
+    /** Short title for the skill */
+    title: string;
+    /** What the agent should do (imperative instruction) */
+    instruction: string;
+    /** When this skill should be applied (scenario description) */
+    trigger: string;
+    /** Key facts extracted from source observations */
+    facts: string[];
+    /** Project this skill belongs to */
+    projectId: string;
+    /** ISO timestamp */
+    createdAt: string;
+    /** How many times this skill was injected in session_start */
+    usedCount: number;
+    /** Classification tags */
+    tags: string[];
+    /** Frozen source observation content at promote time (JSON, immutable provenance proof) */
+    sourceSnapshot?: string;
+    /** ISO timestamp of last modification (Phase 3a: set once at creation) */
+    updatedAt?: string;
+}
+/** A single observation entry within a source snapshot */
+interface SnapshotObservation {
+    id: number;
+    title: string;
+    type: string;
+    narrative: string;
+    facts: string[];
+    entityName: string;
+    projectId: string;
+    createdAt: string;
+    /** Frozen source detail for provenance (explicit / hook / git-ingest) */
+    sourceDetail?: string;
+}
+/** Frozen source content captured at promote time */
+interface SourceSnapshot {
+    observations: SnapshotObservation[];
+    promotedAt: string;
+}
+/** Classification of knowledge for layer-aware ranking */
+type KnowledgeLayer = 'project-truth' | 'promoted' | 'evidence';
+/** Document type discriminator for Orama index */
+type DocumentType = 'observation' | 'mini-skill';
+/** A typed reference to a memory object (observation or mini-skill) */
+interface MemoryRef {
+    kind: 'obs' | 'skill';
+    id: number;
+    projectId?: string;
+}
+/** MCP config format adapter interface */
+interface MCPConfigAdapter {
+    readonly source: AgentTarget;
+    /** Parse MCP server entries from a config file */
+    parse(content: string): MCPServerEntry[];
+    /** Generate config file content from MCP server entries */
+    generate(servers: MCPServerEntry[]): string;
+    /** Get the default config file path for this agent */
+    getConfigPath(projectRoot?: string): string;
+}
+
+export { type AgentTarget, DEFAULT_CONFIG, type DetectionFailure, type DetectionFailureReason, type DetectionResult, type DocumentType, type Entity, type IndexEntry, type KnowledgeGraph, type KnowledgeLayer, type MCPConfigAdapter, type MCPServerEntry, type MemorixConfig, type MemorixDocument, type MemoryRef, type MiniSkill, OBSERVATION_ICONS, type Observation, type ObservationRef, type ObservationStatus, type ObservationType, type ProgressInfo, type ProjectInfo, type Relation, type RuleFormatAdapter, type RuleSource, type SearchOptions, type Session, type SkillConflict, type SkillEntry, type SnapshotObservation, type SourceSnapshot, TOPIC_KEY_FAMILIES, type TimelineContext, type UnifiedRule, type WorkflowEntry, type WorkspaceSyncResult };

package/dist/types.js

@@ -0,0 +1,32 @@
+// 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}"
+};
+var TOPIC_KEY_FAMILIES = {
+  "architecture": ["architecture", "design", "adr", "structure", "pattern"],
+  "bug": ["bugfix", "fix", "error", "regression", "crash", "problem-solution"],
+  "decision": ["decision", "trade-off", "choice", "strategy"],
+  "config": ["config", "setup", "env", "environment", "deployment"],
+  "discovery": ["discovery", "learning", "insight", "gotcha"],
+  "pattern": ["pattern", "convention", "standard", "best-practice"]
+};
+var DEFAULT_CONFIG = {
+  enableEmbeddings: false,
+  enableRulesSync: false,
+  watchRuleFiles: false
+};
+export {
+  DEFAULT_CONFIG,
+  OBSERVATION_ICONS,
+  TOPIC_KEY_FAMILIES
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Open-source cross-agent memory layer for coding agents across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, Copilot, Kiro, OpenCode, Antigravity, and Trae via MCP.",
   "type": "module",
   "sideEffects": false,
@@ -13,23 +13,42 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/types.js",
+      "types": "./dist/types.d.ts"
     }
   },
   "files": [
-    "dist",
+    "dist/index.js",
+    "dist/index.js.map",
+    "dist/index.d.ts",
+    "dist/types.js",
+    "dist/types.js.map",
+    "dist/types.d.ts",
+    "dist/cli/index.js",
+    "dist/cli/index.js.map",
+    "dist/cli/index.d.ts",
+    "dist/dashboard/static/app.js",
+    "dist/dashboard/static/index.html",
+    "dist/dashboard/static/style.css",
+    "dist/dashboard/static/logo.png",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
     "CLAUDE.md",
     "llms.txt",
-    "llms-full.txt"
+    "llms-full.txt",
+    "README.zh-CN.md"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
     "dev": "tsup --watch",
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:llm-live": "MEMORIX_RUN_LIVE_LLM_TESTS=1 vitest run tests/integration/formation-llm-quality.test.ts",
+    "test:e2e": "vitest run tests/e2e/",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build && npm test"
   },
@@ -96,9 +115,11 @@
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^3.0.0",
+    "better-sqlite3": "^11.0.0",
     "fastembed": "^1.14.4"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
     "@types/diff": "^7.0.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.2.14",