memorix 1.2.6 → 1.2.7

package/dist/types.d.ts

@@ -141,6 +141,43 @@ interface Session {
     /** Agent/IDE that started this session */
     agent?: string;
 }
+/** Whether a checkpoint is still waiting for host compaction or has completed. */
+type CompactionCheckpointPhase = 'pre' | 'complete';
+/** Native compaction reason when the host exposes it. */
+type CompactionReason = 'manual' | 'auto' | 'unknown';
+/** How much first-party compaction evidence the host actually exposed. */
+type CompactionCaptureKind = 'preflight' | 'lifecycle' | 'native-summary';
+/** Lifecycle state for a persisted compaction checkpoint. */
+type CompactionCheckpointStatus = 'active' | 'archived';
+/**
+ * A source-aware record of one host-native context compaction.
+ *
+ * This is intentionally not an Observation: a host summary is evidence for
+ * continuation, not automatically durable project truth.
+ */
+interface CompactionCheckpoint {
+    id: string;
+    projectId: string;
+    sessionId: string;
+    agent: string;
+    phase: CompactionCheckpointPhase;
+    captureKind: CompactionCaptureKind;
+    reason: CompactionReason;
+    sourceEvent: string;
+    sourceKey: string;
+    summary?: string;
+    tokensBefore?: number;
+    firstKeptEntryId?: string;
+    details?: Record<string, unknown>;
+    transcriptAvailable: boolean;
+    status: CompactionCheckpointStatus;
+    preCapturedAt: string;
+    completedAt?: string;
+    deliveredAt?: string;
+    deliveryCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
 /** L1 index entry — lightweight, ~50-100 tokens per result */
 interface IndexEntry {
     id: number;
@@ -453,4 +490,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 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 };
+export { type AgentTarget, type CompactionCaptureKind, type CompactionCheckpoint, type CompactionCheckpointPhase, type CompactionCheckpointStatus, type CompactionReason, 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/** 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":[]}
+{"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// Cross-Agent Compaction Continuity\n// ============================================================\n\n/** Whether a checkpoint is still waiting for host compaction or has completed. */\nexport type CompactionCheckpointPhase = 'pre' | 'complete';\n\n/** Native compaction reason when the host exposes it. */\nexport type CompactionReason = 'manual' | 'auto' | 'unknown';\n\n/** How much first-party compaction evidence the host actually exposed. */\nexport type CompactionCaptureKind = 'preflight' | 'lifecycle' | 'native-summary';\n\n/** Lifecycle state for a persisted compaction checkpoint. */\nexport type CompactionCheckpointStatus = 'active' | 'archived';\n\n/**\n * A source-aware record of one host-native context compaction.\n *\n * This is intentionally not an Observation: a host summary is evidence for\n * continuation, not automatically durable project truth.\n */\nexport interface CompactionCheckpoint {\n  id: string;\n  projectId: string;\n  sessionId: string;\n  agent: string;\n  phase: CompactionCheckpointPhase;\n  captureKind: CompactionCaptureKind;\n  reason: CompactionReason;\n  sourceEvent: string;\n  sourceKey: string;\n  summary?: string;\n  tokensBefore?: number;\n  firstKeptEntryId?: string;\n  details?: Record<string, unknown>;\n  transcriptAvailable: boolean;\n  status: CompactionCheckpointStatus;\n  preCapturedAt: string;\n  completedAt?: string;\n  deliveredAt?: string;\n  deliveryCount: number;\n  createdAt: string;\n  updatedAt: 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;AA0OO,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.7-CONTEXT-CONTINUITY.md

@@ -0,0 +1,68 @@
+# 1.2.7 Context Continuity
+
+## Purpose
+
+Host agents own their own `/compact` implementation. Memorix does not replace
+the host compactor, rewrite its prompt, or pretend that every hook exposes a
+summary. Its job is narrower: preserve a small, source-aware continuity record
+so one compacted session, a new window, or another configured agent can resume
+without replaying a transcript.
+
+## Data Boundary
+
+Compact checkpoints live in `compaction_checkpoints` in the local SQLite data
+store. They are not Observations, claims, Knowledge Workspace pages, or
+transcript archives.
+
+- A `pre` marker says the host is about to compact.
+- A `complete` checkpoint records either a genuine `native-summary` or an
+  honest `lifecycle` completion with no summary.
+- Repeated hook delivery is idempotent. A second real compact in the same
+  session creates a new checkpoint when the host provides a fresh preflight
+  marker or native compaction event ID.
+- Checkpoints are never automatically promoted into durable memory.
+
+## Host Capability
+
+| Host path | Evidence Memorix stores | Automatic delivery |
+| --- | --- | --- |
+| Pi / Oh-my-Pi package extension | Native compaction entry fields when exposed by the host, including summary and token metadata | Explicit continuation Workset or `memorix checkpoint context` |
+| Codex plugin hooks | `PreCompact` marker plus `SessionStart` compact lifecycle completion | One bounded `SessionStart.additionalContext` delivery |
+| Claude Code hooks | `PreCompact` marker plus compact `SessionStart` lifecycle completion | One bounded next `UserPromptSubmit.additionalContext` delivery |
+| Other hook integrations | Only the fields their official event surface actually provides | Explicit CLI/MCP inspection unless that host has a documented context injection point |
+
+`manual`, `auto`, and native summary fields are retained only when the host
+payload reports them. Unknown remains `unknown`.
+
+## Agent Experience
+
+For normal work, nothing new needs to be typed. The native compact path uses a
+single bounded recovery packet when the host supports an official injection
+channel. It contains current task wording, the host/source label, and at most a
+small checkpoint excerpt. It never contains a full conversation transcript.
+
+For Claude Code, a handoff or continuation prompt also receives one short
+`UserPromptSubmit` routing hint to call `memorix_project_context` before broad
+file or Git exploration. The hint is not a memory dump, and unrelated feature
+or documentation prompts remain quiet.
+
+For an explicit cross-agent handoff or a CLI-only agent:
+
+```bash
+memorix resume "continue the authentication regression"
+memorix checkpoint list
+memorix checkpoint context --task "continue the authentication regression"
+```
+
+`memorix resume` can add one recent checkpoint to its normal continuation
+Workset. The item is labelled as historical host lifecycle evidence and current
+code remains authoritative. A checkpoint older than 24 hours is not
+automatically added; it remains inspectable through the CLI.
+
+## MCP Surface
+
+The normal MCP profiles remain unchanged. The advanced action tool
+`memorix_compaction_checkpoint` is available only with `--mode full` or
+`MEMORIX_MODE=full` and supports `list`, `show`, `context`, and `archive`.
+This keeps ordinary agent tool schemas small while preserving a complete
+inspection path for debugging and handoff work.

package/docs/API_REFERENCE.md

@@ -98,6 +98,8 @@ memorix context
 memorix context --task "continue auth bug"
 memorix context "continue auth bug"
 memorix resume "continue auth bug"
+memorix checkpoint list
+memorix checkpoint context --task "continue auth bug"
 memorix context --task "prepare 1.1.7 release"
 memorix explain
 memorix codegraph context-pack --task "continue auth bug"
@@ -109,11 +111,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. 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.
+`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, up to three readable durable memories, and at most one recent source-labelled compact checkpoint. Checkpoints are host lifecycle evidence, not durable memory or transcript backups; 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`, 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.
+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. After a native compact, Codex receives one bounded checkpoint through its official `SessionStart` compact context channel. Claude Code receives one bounded checkpoint through the next official `UserPromptSubmit` context channel, then delivery stops. Pi and Oh-my-Pi retain the native summary fields their extension API exposes; hosts that do not expose a summary remain labelled as lifecycle-only. 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.
 
@@ -138,6 +140,8 @@ memorix knowledge workflow preview --id <workflow-id> --agent codex
 
 The advanced MCP action tool is `memorix_knowledge`. It is registered only in the `team` and `full` tool profiles so normal agents keep the compact micro/lite tool surface. Its actions are `workspace_init`, `status`, `claim_list`, `claim_review`, `compile`, `lint`, `proposal_apply`, `workflow_import`, `workflow_list`, `workflow_select`, `workflow_preview`, `workflow_apply`, and `workflow_run`. Explicit agent observations become `needs-review` claim candidates: check their source evidence, then use `claim_review` with a reason to approve or reject them. Only approved claims can be compiled into publishable Knowledge Workspace pages. Ordinary coding work should stay on `memorix_project_context`.
 
+`memorix_compaction_checkpoint` is a separate advanced MCP action tool registered only in the `full` profile. Its `list`, `show`, `context`, and `archive` actions match `memorix checkpoint` for explicit continuity inspection. Normal agents should not call it during ordinary work; automatic recovery and `memorix_project_context` already handle the bounded path.
+
 ### Cross-Agent Handoff Receipt
 
 `memorix receipt` creates a privacy-safe diagnostic artifact for cross-agent memory handoff debugging.

package/docs/dev-log/progress.txt

@@ -316,3 +316,26 @@
   `memcode` version parity, all seven versioned plugin manifests, both Context
   CLI forms, and a real stdio MCP handshake: 43 tools were discoverable and
   `memorix_project_context` returned an Autopilot Brief.
+
+## 1.2.7 Native Context Continuity
+- Added a project-scoped SQLite checkpoint store that separates host-native
+  compaction evidence from Observations, claims, Knowledge Workspace pages,
+  and transcript storage. It captures preflight markers, native summaries
+  where the host exposes them, lifecycle-only completion where it does not,
+  idempotent retry handling, one-time delivery state, and archival.
+- Pi and Oh-my-Pi extensions now pass through their real `compactionEntry`
+  fields. Codex and Claude Code use their documented compact lifecycle paths
+  without fabricating a host summary or changing the host compactor.
+- Codex consumes one bounded checkpoint at compact `SessionStart`; Claude Code
+  consumes one on the next official `UserPromptSubmit` delivery point. Explicit
+  CLI/MCP continuation can carry at most one recent source-labelled checkpoint
+  across configured agents, while ordinary new tasks remain free of it.
+- Added `memorix checkpoint list|show|context|archive` and the full-profile
+  `memorix_compaction_checkpoint` MCP action. The default MCP profile remains
+  unchanged to protect agent context budgets.
+- Final verification passed: focused compaction, hook, Workset, CLI, and MCP
+  tests; the full root test suite; TypeScript check; production build; npm
+  package dry-run; an isolated installed-artifact Codex/CLI/MCP smoke; and an
+  isolated Claude Code handoff/continuation smoke. `npm publish --dry-run
+  --ignore-scripts` accepted the public 1.2.7 tarball; the full prepublish
+  build/test path is covered by the root release gates above.

package/docs/hooks-architecture.md

@@ -68,7 +68,8 @@ memorix hook <normalized_event> [--agent <agent_name>]
 | `post_edit` | 分析变更 → 记录 what-changed |
 | `post_command` | 分析命令结果 → 记录 problem-solution (如有错误) |
 | `post_tool` | 分析 MCP 工具调用 → 记录相关操作 |
-| `pre_compact` | 压缩前保存当前上下文摘要 |
+| `pre_compact` | 记录压缩前检查点；不把宿主未提供的内容伪造成摘要 |
+| `post_compact` | 完成检查点；仅在宿主真实提供原生摘要时保存该摘要 |
 | `session_end` | 总结本次会话 → 记录决策和发现 |
 | `user_prompt` | 模式检测 → 判断是否需要注入记忆 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

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

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

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/extensions/memorix.js

@@ -38,6 +38,20 @@ function latestAssistantText(messages) {
   return '';
 }
 
+function compactionEntryPayload(entry) {
+  if (!entry || typeof entry !== 'object') return undefined;
+  const payload = {
+    id: typeof entry.id === 'string' ? entry.id : undefined,
+    summary: typeof entry.summary === 'string' ? entry.summary : undefined,
+    tokensBefore: typeof entry.tokensBefore === 'number' ? entry.tokensBefore : undefined,
+    firstKeptEntryId: typeof entry.firstKeptEntryId === 'string' ? entry.firstKeptEntryId : undefined,
+  };
+  if (entry.details && typeof entry.details === 'object') {
+    payload.details = entry.details;
+  }
+  return payload;
+}
+
 function runMemorix(args, input) {
   const command = process.platform === 'win32' ? 'memorix.cmd' : 'memorix';
   const result = spawnSync(command, args, {
@@ -147,6 +161,7 @@ export default function memorixOmpExtension(pi) {
     runHook({
       hook_event_name: 'omp.session_before_compact',
       cwd: ctx.cwd,
+      compaction_reason: 'unknown',
     });
   });
 
@@ -154,6 +169,8 @@ export default function memorixOmpExtension(pi) {
     runHook({
       hook_event_name: 'omp.session_compact',
       cwd: ctx.cwd,
+      compaction_entry: compactionEntryPayload(event.compactionEntry),
+      from_extension: event.fromExtension === true,
     });
   });
 

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

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

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

package/plugins/pi/memorix/extensions/memorix.js

@@ -38,6 +38,20 @@ function latestAssistantText(messages) {
   return '';
 }
 
+function compactionEntryPayload(entry) {
+  if (!entry || typeof entry !== 'object') return undefined;
+  const payload = {
+    id: typeof entry.id === 'string' ? entry.id : undefined,
+    summary: typeof entry.summary === 'string' ? entry.summary : undefined,
+    tokensBefore: typeof entry.tokensBefore === 'number' ? entry.tokensBefore : undefined,
+    firstKeptEntryId: typeof entry.firstKeptEntryId === 'string' ? entry.firstKeptEntryId : undefined,
+  };
+  if (entry.details && typeof entry.details === 'object') {
+    payload.details = entry.details;
+  }
+  return payload;
+}
+
 function runHook(payload) {
   const data = JSON.stringify({
     agent: 'pi',
@@ -137,6 +151,7 @@ export default function memorixPiExtension(pi) {
     runHook({
       hook_event_name: 'pi.session_before_compact',
       cwd: ctx.cwd,
+      compaction_reason: 'unknown',
     });
   });
 
@@ -144,6 +159,8 @@ export default function memorixPiExtension(pi) {
     runHook({
       hook_event_name: 'pi.session_compact',
       cwd: ctx.cwd,
+      compaction_entry: compactionEntryPayload(event.compactionEntry),
+      from_extension: event.fromExtension === true,
     });
   });
 

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/src/cli/capability-map.ts

@@ -5,6 +5,7 @@ export const CLI_NATIVE_PARITY: Record<string, string> = Object.freeze({
   memorix_graph_context: 'memorix memory graph-context',
   memorix_project_context: 'memorix context|resume',
   memorix_context_pack: 'memorix codegraph context-pack',
+  memorix_compaction_checkpoint: 'memorix checkpoint list|show|context|archive',
   memorix_codegraph_status: 'memorix codegraph status',
   memorix_knowledge: 'memorix knowledge init|status|compile|lint|apply|workflow',
   memorix_resolve: 'memorix memory resolve',

package/src/cli/command-guide.ts

@@ -56,6 +56,16 @@ const GUIDES: Record<string, CliCommandGuide> = {
       'memorix codegraph context-pack --task "trace the auth flow" [--limit 20]',
     ],
   },
+  checkpoint: {
+    summary: 'Inspect bounded recovery checkpoints created around host-native context compaction.',
+    usage: [
+      'memorix checkpoint list [--session <id>] [--agent <name>]',
+      'memorix checkpoint show --id <checkpoint-id>',
+      'memorix checkpoint context [--id <checkpoint-id>] [--task "continue auth fix"]',
+      'memorix checkpoint archive --id <checkpoint-id>',
+    ],
+    notes: ['Checkpoints are host lifecycle evidence, not durable project memory and not transcript backups.'],
+  },
   knowledge: {
     summary: 'Manage the reviewed, source-backed Knowledge Workspace and project workflows.',
     usage: [

package/src/cli/commands/checkpoint.ts

@@ -0,0 +1,144 @@
+import { defineCommand } from 'citty';
+import { buildCompactionWorkset } from '../../memory/compaction.js';
+import { CompactionCheckpointStore } from '../../store/compaction-checkpoint-store.js';
+import type { CompactionCheckpoint } from '../../types.js';
+import {
+  emitError,
+  emitResult,
+  getCliProjectContext,
+  parsePositiveInt,
+  shortId,
+} from './operator-shared.js';
+
+async function getCheckpointContext() {
+  const context = await getCliProjectContext();
+  const { initAliasRegistry, registerAlias } = await import('../../project/aliases.js');
+  initAliasRegistry(context.dataDir);
+  const canonicalId = await registerAlias(context.project);
+  return {
+    ...context,
+    project: { ...context.project, id: canonicalId },
+    store: new CompactionCheckpointStore(context.dataDir),
+  };
+}
+
+function assertProjectCheckpoint(
+  checkpoint: CompactionCheckpoint | undefined,
+  projectId: string,
+  id: string,
+): CompactionCheckpoint {
+  if (!checkpoint || checkpoint.projectId !== projectId) {
+    throw new Error(`No compact checkpoint "${id}" exists for this project.`);
+  }
+  return checkpoint;
+}
+
+function formatCheckpoint(checkpoint: CompactionCheckpoint): string {
+  const completion = checkpoint.completedAt ? `, completed ${checkpoint.completedAt}` : '';
+  const delivery = checkpoint.deliveredAt ? `, delivered ${checkpoint.deliveryCount}x` : '';
+  return [
+    `${shortId(checkpoint.id)} ${checkpoint.phase} ${checkpoint.agent} (${checkpoint.captureKind}, ${checkpoint.reason})`,
+    `  session: ${checkpoint.sessionId}`,
+    `  source: ${checkpoint.sourceEvent}${completion}${delivery}`,
+    `  status: ${checkpoint.status}${checkpoint.transcriptAvailable ? ', transcript marker available' : ''}`,
+    ...(checkpoint.summary ? [`  summary: ${checkpoint.summary.replace(/\s+/g, ' ').slice(0, 220)}`] : []),
+  ].join('\n');
+}
+
+function usage(): void {
+  console.log('Memorix Compact Checkpoints');
+  console.log('');
+  console.log('Usage:');
+  console.log('  memorix checkpoint list [--session <id>] [--agent <name>] [--all]');
+  console.log('  memorix checkpoint show --id <checkpoint-id>');
+  console.log('  memorix checkpoint context [--id <checkpoint-id>] [--task "..."] [--budget 420]');
+  console.log('  memorix checkpoint archive --id <checkpoint-id>');
+}
+
+export default defineCommand({
+  meta: {
+    name: 'checkpoint',
+    description: 'Inspect and manage native compact continuity checkpoints',
+  },
+  args: {
+    id: { type: 'string', description: 'Checkpoint ID' },
+    session: { type: 'string', description: 'Filter by host session ID' },
+    agent: { type: 'string', description: 'Filter by host agent name' },
+    task: { type: 'string', description: 'Current task for a bounded continuation workset' },
+    budget: { type: 'string', description: 'Maximum workset token budget (default: 420)' },
+    limit: { type: 'string', description: 'Maximum checkpoints to list (default: 20)' },
+    all: { type: 'boolean', description: 'Include archived checkpoints in list output' },
+    json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+  },
+  run: async ({ args }) => {
+    const positional = (args._ as string[]) ?? [];
+    const action = (positional[0] ?? 'list').toLowerCase();
+    const asJson = Boolean(args.json);
+
+    try {
+      const { project, store } = await getCheckpointContext();
+      const id = (args.id as string | undefined)?.trim();
+
+      switch (action) {
+        case 'list': {
+          const checkpoints = store.list({
+            projectId: project.id,
+            sessionId: (args.session as string | undefined)?.trim() || undefined,
+            agent: (args.agent as string | undefined)?.trim() || undefined,
+            includeArchived: Boolean(args.all),
+            limit: parsePositiveInt(args.limit as string | undefined, 20),
+          });
+          emitResult(
+            { project, checkpoints },
+            checkpoints.length
+              ? checkpoints.map(formatCheckpoint).join('\n\n')
+              : 'No compact checkpoints for this project.',
+            asJson,
+          );
+          return;
+        }
+
+        case 'show': {
+          if (!id) throw new Error('id is required for "memorix checkpoint show".');
+          const checkpoint = assertProjectCheckpoint(store.get(id), project.id, id);
+          emitResult({ project, checkpoint }, formatCheckpoint(checkpoint), asJson);
+          return;
+        }
+
+        case 'context': {
+          const checkpoint = id
+            ? assertProjectCheckpoint(store.get(id), project.id, id)
+            : store.list({
+              projectId: project.id,
+              sessionId: (args.session as string | undefined)?.trim() || undefined,
+              agent: (args.agent as string | undefined)?.trim() || undefined,
+              limit: parsePositiveInt(args.limit as string | undefined, 20),
+            }).find((entry) => entry.phase === 'complete');
+          if (!checkpoint) {
+            throw new Error('No completed compact checkpoint is available for this project and filter.');
+          }
+          const workset = buildCompactionWorkset(checkpoint, {
+            task: (args.task as string | undefined)?.trim(),
+            maxTokens: parsePositiveInt(args.budget as string | undefined, 420),
+          });
+          emitResult({ project, checkpoint, workset }, workset.text, asJson);
+          return;
+        }
+
+        case 'archive': {
+          if (!id) throw new Error('id is required for "memorix checkpoint archive".');
+          assertProjectCheckpoint(store.get(id), project.id, id);
+          const checkpoint = store.archive(id);
+          if (!checkpoint) throw new Error(`Compact checkpoint "${id}" is already archived.`);
+          emitResult({ project, checkpoint }, `Archived compact checkpoint ${shortId(checkpoint.id)}.`, asJson);
+          return;
+        }
+
+        default:
+          usage();
+      }
+    } catch (error) {
+      emitError(error instanceof Error ? error.message : String(error), asJson);
+    }
+  },
+});