memorix 1.2.0 → 1.2.2

package/src/git/hooks-path.ts

@@ -1,85 +1,85 @@
-/**
- * Git hooks path resolver — worktree-safe.
- *
- * In a normal repo:   .git is a directory  → hooks at .git/hooks/
- * In a git worktree:  .git is a FILE containing "gitdir: /path/to/actual/git/dir"
- *                     → hooks at that resolved path + /hooks/
- *
- * This utility ensures all hook install/uninstall/check operations
- * work correctly in both scenarios.
- */
-
-import { existsSync, readFileSync, statSync, mkdirSync } from 'node:fs';
-import path from 'node:path';
-
-/**
- * Resolve the actual .git directory path, following worktree indirection.
- *
- * @param projectRoot - The root of the working tree (where .git lives)
- * @returns Absolute path to the real git dir, or null if no .git found
- */
-export function resolveGitDir(projectRoot: string): string | null {
-  const dotGit = path.join(projectRoot, '.git');
-
-  if (!existsSync(dotGit)) return null;
-
-  const stat = statSync(dotGit);
-
-  if (stat.isDirectory()) {
-    // Normal repo — .git is a directory
-    return dotGit;
-  }
-
-  if (stat.isFile()) {
-    // Worktree — .git is a file: "gitdir: /path/to/actual/git/dir"
-    try {
-      const content = readFileSync(dotGit, 'utf-8').trim();
-      const match = content.match(/^gitdir:\s*(.+)$/);
-      if (match) {
-        const gitdir = match[1].trim();
-        // Resolve relative paths against the project root
-        const resolved = path.isAbsolute(gitdir)
-          ? gitdir
-          : path.resolve(projectRoot, gitdir);
-        if (existsSync(resolved)) {
-          return resolved;
-        }
-      }
-    } catch {
-      // Unreadable .git file — fall through
-    }
-  }
-
-  return null;
-}
-
-/**
- * Resolve the hooks directory for a project (read-only — does NOT create directories).
- * Handles both normal repos and git worktrees.
- *
- * @param projectRoot - The root of the working tree
- * @returns Object with hooksDir and hookPath for post-commit, or null if no .git found
- */
-export function resolveHooksDir(projectRoot: string): { hooksDir: string; hookPath: string } | null {
-  const gitDir = resolveGitDir(projectRoot);
-  if (!gitDir) return null;
-
-  const hooksDir = path.join(gitDir, 'hooks');
-
-  return {
-    hooksDir,
-    hookPath: path.join(hooksDir, 'post-commit'),
-  };
-}
-
-/**
- * Resolve hooks directory AND ensure it exists on disk.
- * Use this only in write paths (hook install / autoHook).
- */
-export function ensureHooksDir(projectRoot: string): { hooksDir: string; hookPath: string } | null {
-  const resolved = resolveHooksDir(projectRoot);
-  if (!resolved) return null;
-
-  mkdirSync(resolved.hooksDir, { recursive: true });
-  return resolved;
-}
+/**
+ * Git hooks path resolver — worktree-safe.
+ *
+ * In a normal repo:   .git is a directory  → hooks at .git/hooks/
+ * In a git worktree:  .git is a FILE containing "gitdir: /path/to/actual/git/dir"
+ *                     → hooks at that resolved path + /hooks/
+ *
+ * This utility ensures all hook install/uninstall/check operations
+ * work correctly in both scenarios.
+ */
+
+import { existsSync, readFileSync, statSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Resolve the actual .git directory path, following worktree indirection.
+ *
+ * @param projectRoot - The root of the working tree (where .git lives)
+ * @returns Absolute path to the real git dir, or null if no .git found
+ */
+export function resolveGitDir(projectRoot: string): string | null {
+  const dotGit = path.join(projectRoot, '.git');
+
+  if (!existsSync(dotGit)) return null;
+
+  const stat = statSync(dotGit);
+
+  if (stat.isDirectory()) {
+    // Normal repo — .git is a directory
+    return dotGit;
+  }
+
+  if (stat.isFile()) {
+    // Worktree — .git is a file: "gitdir: /path/to/actual/git/dir"
+    try {
+      const content = readFileSync(dotGit, 'utf-8').trim();
+      const match = content.match(/^gitdir:\s*(.+)$/);
+      if (match) {
+        const gitdir = match[1].trim();
+        // Resolve relative paths against the project root
+        const resolved = path.isAbsolute(gitdir)
+          ? gitdir
+          : path.resolve(projectRoot, gitdir);
+        if (existsSync(resolved)) {
+          return resolved;
+        }
+      }
+    } catch {
+      // Unreadable .git file — fall through
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the hooks directory for a project (read-only — does NOT create directories).
+ * Handles both normal repos and git worktrees.
+ *
+ * @param projectRoot - The root of the working tree
+ * @returns Object with hooksDir and hookPath for post-commit, or null if no .git found
+ */
+export function resolveHooksDir(projectRoot: string): { hooksDir: string; hookPath: string } | null {
+  const gitDir = resolveGitDir(projectRoot);
+  if (!gitDir) return null;
+
+  const hooksDir = path.join(gitDir, 'hooks');
+
+  return {
+    hooksDir,
+    hookPath: path.join(hooksDir, 'post-commit'),
+  };
+}
+
+/**
+ * Resolve hooks directory AND ensure it exists on disk.
+ * Use this only in write paths (hook install / autoHook).
+ */
+export function ensureHooksDir(projectRoot: string): { hooksDir: string; hookPath: string } | null {
+  const resolved = resolveHooksDir(projectRoot);
+  if (!resolved) return null;
+
+  mkdirSync(resolved.hooksDir, { recursive: true });
+  return resolved;
+}

package/src/hooks/admission.ts

@@ -0,0 +1,117 @@
+import type { ObservationAdmissionState, ObservationType } from '../types.js';
+import { isSignificantKnowledge } from './significance-filter.js';
+import type { NormalizedHookInput } from './types.js';
+
+export type HookCaptureCategory =
+  | 'file_modify'
+  | 'file_read'
+  | 'command'
+  | 'search'
+  | 'memorix_internal'
+  | 'unknown';
+
+export type HookAdmissionDecision =
+  | { action: 'drop'; reason: string }
+  | {
+    action: 'store';
+    admissionState: ObservationAdmissionState;
+    admissionReason: string;
+    valueCategory: 'core' | 'contextual' | 'ephemeral';
+  };
+
+const FAILURE_PATTERN = /\b(fail(?:ed|ure)?|error|exception|assert(?:ion)?|exit code [1-9]|TypeError|ReferenceError|SyntaxError|ENOENT|ECONNREFUSED|panic)\b/i;
+const DECISION_PATTERN = /\b(decision|decided|choose|chosen|because|trade-?off|invariant|root cause|workaround|must|should not)\b/i;
+const TASK_PATTERN = /\b(add|implement|fix|refactor|migrate|upgrade|debug|investigate|test|release|deploy|remove)\b/i;
+const VALIDATION_PATTERN = /\b(test|tests|vitest|jest|pytest|playwright|cypress|typecheck|lint|build|cargo test|go test)\b/i;
+const FOCUSED_VALIDATION_PATTERN = /(?:--run|--filter|--grep|\s-t\s|\.test\.|\.spec\.|::[\w-]+)/i;
+const ROUTINE_SUCCESS_PATTERN = /\b(added \d+ packages|up to date|passed|all tests pass|tests? passed|0 failures|success(?:fully)?)\b/i;
+
+function isCandidateType(type: ObservationType): boolean {
+  return type === 'decision' ||
+    type === 'gotcha' ||
+    type === 'problem-solution' ||
+    type === 'trade-off' ||
+    type === 'why-it-exists';
+}
+
+function candidate(
+  admissionReason: string,
+  valueCategory: 'core' | 'contextual' = 'contextual',
+): HookAdmissionDecision {
+  return { action: 'store', admissionState: 'candidate', admissionReason, valueCategory };
+}
+
+function ephemeral(admissionReason: string): HookAdmissionDecision {
+  return { action: 'store', admissionState: 'ephemeral', admissionReason, valueCategory: 'ephemeral' };
+}
+
+/**
+ * Cheap, deterministic first-pass admission for cross-agent hooks. It never
+ * promotes an automatic record directly to durable context: background
+ * qualification must still prove a current Code Memory reference.
+ */
+export function assessHookAdmission(input: {
+  hook: NormalizedHookInput;
+  category: HookCaptureCategory;
+  content: string;
+  observationType: ObservationType;
+}): HookAdmissionDecision {
+  const { hook, category, content, observationType } = input;
+  const command = hook.command ?? '';
+  const hasFailure = FAILURE_PATTERN.test(content);
+  const hasDecision = DECISION_PATTERN.test(content) || isCandidateType(observationType);
+  const isValidation = VALIDATION_PATTERN.test(command) || VALIDATION_PATTERN.test(content);
+  const isFocusedValidation = FOCUSED_VALIDATION_PATTERN.test(command);
+  const isRoutineSuccess = ROUTINE_SUCCESS_PATTERN.test(content);
+
+  if (hasFailure) {
+    return candidate('automatic capture contains a concrete failure or verification signal');
+  }
+  if (hasDecision) {
+    return candidate('automatic capture contains a decision or durable rationale', 'core');
+  }
+
+  if (hook.event === 'user_prompt') {
+    return TASK_PATTERN.test(content)
+      ? candidate('user task contains a concrete technical action')
+      : { action: 'drop', reason: 'prompt has no durable technical task signal' };
+  }
+
+  if (hook.event === 'post_response') {
+    // Agent integrations such as OpenCode emit concise end-of-turn summaries.
+    // Keep technically meaningful ones as candidates; qualification still
+    // prevents them from becoming automatic context without code evidence.
+    return isSignificantKnowledge(content).isSignificant
+      ? candidate('assistant response records a concrete technical outcome')
+      : { action: 'drop', reason: 'response has no durable technical outcome' };
+  }
+
+  if (hook.event === 'session_end') {
+    // The handler already applies a minimum-content gate for session end.
+    // Preserve a compact handoff trace, but keep it out of automatic context
+    // until later qualification.
+    return candidate('session-end summary awaits Code Memory qualification');
+  }
+
+  if (category === 'file_modify') {
+    return candidate('file mutation awaits Code Memory qualification');
+  }
+
+  if (category === 'command') {
+    if (isValidation && isFocusedValidation && !isRoutineSuccess) {
+      return candidate('focused validation result awaits Code Memory qualification');
+    }
+    if (isValidation || isRoutineSuccess) {
+      return ephemeral('routine command result retained only as a short-lived trace');
+    }
+    return ephemeral('command activity retained only as a short-lived trace');
+  }
+
+  if (category === 'search' || category === 'unknown') {
+    return content.length >= 300
+      ? ephemeral('unverified automatic activity retained only as a short-lived trace')
+      : { action: 'drop', reason: 'automatic activity has insufficient evidence' };
+  }
+
+  return { action: 'drop', reason: 'capture category is not eligible for automatic storage' };
+}

package/src/hooks/handler.ts

@@ -2,15 +2,21 @@
  * Hook Handler
  *
  * Unified entry point for all agent hooks.
- * Architecture: Normalize → Classify → Policy → Store → Respond
+ * Architecture: Normalize → Classify → Admit → Store → Respond
  *
  * Design principles (inspired by claude-mem + mcp-memory-service):
- * - Store-first: capture generously, filter at read time
+ * - Candidate-first: automatic capture is never durable context by default
  * - Tool Taxonomy: declarative policies per tool category
  * - Pattern = classification only: determines observation type, not storage
  */
 
+import { createHash } from 'node:crypto';
 import type { ObservationType } from '../types.js';
+import {
+  assessHookAdmission,
+  type HookAdmissionDecision,
+  type HookCaptureCategory,
+} from './admission.js';
 import { normalizeHookInput } from './normalizer.js';
 import { detectBestPattern, patternToObservationType } from './pattern-detector.js';
 import { isSignificantKnowledge, isRetrievedResult, isTrivialCommand } from './significance-filter.js';
@@ -35,6 +41,11 @@ const MIN_PROMPT_LENGTH = 20;
 /** Max content length (truncate beyond this) */
 const MAX_CONTENT_LENGTH = 4000;
 
+function deriveHookActorId(input: NormalizedHookInput): string {
+  const material = `${input.agent ?? 'unknown'}\u0000${input.sessionId ?? 'unknown'}`;
+  return `hook:${createHash('sha256').update(material).digest('hex').slice(0, 24)}`;
+}
+
 /** Truly trivial commands — standalone navigation/inspection only */
 const NOISE_COMMANDS = [
   /^(ls|dir|cd|pwd|echo|cat|type|head|tail|wc|which|where|whoami)(\s|$)/i,
@@ -49,7 +60,7 @@ const NOISE_COMMANDS = [
 // ─── Tool Taxonomy ───
 
 /** Tool categories for storage policy */
-type ToolCategory = 'file_modify' | 'file_read' | 'command' | 'search' | 'memorix_internal' | 'unknown';
+type ToolCategory = HookCaptureCategory;
 
 /** Storage policy per tool category */
 interface StoragePolicy {
@@ -233,7 +244,12 @@ function generateTitle(input: NormalizedHookInput, patternType: string): string
   return `Activity (${patternType})`;
 }
 
-function buildObservation(input: NormalizedHookInput, content: string, category: ToolCategory) {
+function buildObservation(
+  input: NormalizedHookInput,
+  content: string,
+  category: ToolCategory,
+  admission?: Extract<HookAdmissionDecision, { action: 'store' }>,
+) {
   const pattern = detectBestPattern(content);
   const policy = STORAGE_POLICY[category] ?? STORAGE_POLICY.unknown;
   const fallbackType = input.filePath ? 'what-changed' : policy.defaultType;
@@ -252,6 +268,15 @@ function buildObservation(input: NormalizedHookInput, content: string, category:
     ],
     concepts: pattern?.matchedKeywords ?? [],
     filesModified: input.filePath ? [input.filePath] : [],
+    ...(admission ? {
+      valueCategory: admission.valueCategory,
+      admissionState: admission.admissionState,
+      admissionReason: admission.admissionReason,
+      // Automatic capture is private until current code can qualify it for
+      // shared project delivery. The opaque actor is stable within a hook session.
+      visibility: 'personal' as const,
+      createdByAgentId: deriveHookActorId(input),
+    } : {}),
   };
 }
 
@@ -281,7 +306,9 @@ async function handleSessionStart(input: NormalizedHookInput): Promise<{
       const { initMiniSkillStore } = await import('../store/mini-skill-store.js');
       const { initSessionStore } = await import('../store/session-store.js');
       const { initAliasRegistry, registerAlias } = await import('../project/aliases.js');
+      const { MaintenanceTargetStore } = await import('../runtime/maintenance-targets.js');
       const { buildAutoProjectContext, formatAutoProjectContextPrompt } = await import('../codegraph/auto-context.js');
+      const { filterReadableObservations } = await import('../memory/visibility.js');
 
       const rawProject = detectProject(input.cwd || process.cwd());
       if (!rawProject) throw new Error('No .git found');
@@ -289,10 +316,18 @@ async function handleSessionStart(input: NormalizedHookInput): Promise<{
 
       initAliasRegistry(dataDir);
       const canonicalId = await registerAlias(rawProject);
+      new MaintenanceTargetStore(dataDir).register({
+        projectId: canonicalId,
+        projectRoot: rawProject.rootPath,
+        dataDir,
+      });
       await initObservationStore(dataDir);
       await initMiniSkillStore(dataDir);
       await initSessionStore(dataDir);
-      const activeObservations = await getStore().loadByProject(canonicalId, { status: 'active' });
+      const activeObservations = filterReadableObservations(
+        await getStore().loadByProject(canonicalId, { status: 'active' }),
+        { projectId: canonicalId },
+      );
       const context = await buildAutoProjectContext({
         project: { ...rawProject, id: canonicalId },
         dataDir,
@@ -306,6 +341,7 @@ async function handleSessionStart(input: NormalizedHookInput): Promise<{
               maxFiles: 5_000,
             });
           }),
+        deliveryTarget: 'hook-session-start',
       });
       contextSummary = `\n\n${formatAutoProjectContextPrompt(context)}`;
     } catch (sessErr) {
@@ -352,8 +388,17 @@ async function handleHookEventCore(input: NormalizedHookInput): Promise<{
     if (endContent.length < 50) {
       return { observation: null, output: defaultOutput };
     }
+    const draft = buildObservation(input, endContent, 'unknown');
+    const admission = assessHookAdmission({
+      hook: input,
+      category: 'unknown',
+      content: endContent,
+      observationType: draft.type,
+    });
     return {
-      observation: buildObservation(input, endContent, 'unknown'),
+      observation: admission.action === 'store'
+        ? buildObservation(input, endContent, 'unknown', admission)
+        : null,
       output: defaultOutput,
     };
   }
@@ -425,8 +470,17 @@ async function handleHookEventCore(input: NormalizedHookInput): Promise<{
   }
   markTriggered(cooldownKey);
 
+  const draft = buildObservation(input, content, category);
+  const admission = assessHookAdmission({
+    hook: input,
+    category,
+    content,
+    observationType: draft.type,
+  });
   return {
-    observation: buildObservation(input, content, category),
+    observation: admission.action === 'store'
+      ? buildObservation(input, content, category, admission)
+      : null,
     output: defaultOutput,
   };
 }
@@ -440,17 +494,24 @@ async function queueCodegraphRefreshForMutation(input: NormalizedHookInput): Pro
       { getProjectDataDir },
       { initAliasRegistry, registerAlias },
       { enqueueCodegraphRefresh },
+      { MaintenanceTargetStore },
     ] = await Promise.all([
       import('../project/detector.js'),
       import('../store/persistence.js'),
       import('../project/aliases.js'),
       import('../runtime/lifecycle.js'),
+      import('../runtime/maintenance-targets.js'),
     ]);
     const project = detectProject(input.cwd || process.cwd());
     if (!project) return;
     const dataDir = await getProjectDataDir(project.id);
     initAliasRegistry(dataDir);
     const projectId = await registerAlias(project);
+    new MaintenanceTargetStore(dataDir).register({
+      projectId,
+      projectRoot: project.rootPath,
+      dataDir,
+    });
     enqueueCodegraphRefresh({
       dataDir,
       projectId,
@@ -465,11 +526,25 @@ async function queueCodegraphRefreshForMutation(input: NormalizedHookInput): Pro
 export async function handleHookEvent(input: NormalizedHookInput): Promise<{
   observation: ReturnType<typeof buildObservation> | null;
   output: HookOutput;
+}>;
+export async function handleHookEvent(input: NormalizedHookInput, options: {
+  deferMaintenance?: boolean;
+}): Promise<{
+  observation: ReturnType<typeof buildObservation> | null;
+  output: HookOutput;
+}>;
+export async function handleHookEvent(input: NormalizedHookInput, options: {
+  deferMaintenance?: boolean;
+} = {}): Promise<{
+  observation: ReturnType<typeof buildObservation> | null;
+  output: HookOutput;
 }> {
   try {
     return await handleHookEventCore(input);
   } finally {
-    await queueCodegraphRefreshForMutation(input);
+    // The CLI persists an automatic observation after this function returns.
+    // It defers scheduling so a fast worker never scans before that write.
+    if (!options.deferMaintenance) await queueCodegraphRefreshForMutation(input);
   }
 }
 
@@ -570,7 +645,7 @@ export async function runHook(agentOverride?: string, eventOverride?: string): P
   }
 
   const input = normalizeHookInput(payload);
-  const { observation, output } = await handleHookEvent(input);
+  const { observation, output } = await handleHookEvent(input, { deferMaintenance: true });
 
   if (observation) {
     try {
@@ -581,6 +656,7 @@ export async function runHook(agentOverride?: string, eventOverride?: string): P
       const { detectProject } = await import('../project/detector.js');
       const { getProjectDataDir } = await import('../store/persistence.js');
       const { initAliasRegistry, registerAlias } = await import('../project/aliases.js');
+      const { MaintenanceTargetStore } = await import('../runtime/maintenance-targets.js');
 
       const rawProject = detectProject(input.cwd || process.cwd());
       if (!rawProject) throw new Error('No .git found');
@@ -590,94 +666,20 @@ export async function runHook(agentOverride?: string, eventOverride?: string): P
       initAliasRegistry(dataDir);
       const canonicalId = await registerAlias(rawProject);
       const projectId = canonicalId;
+      new MaintenanceTargetStore(dataDir).register({
+        projectId,
+        projectRoot: rawProject.rootPath,
+        dataDir,
+      });
       
       await initObservationStore(dataDir);
       await initMSStore(dataDir);
       await initSessStore(dataDir);
       await initObservations(dataDir);
       await storeObservation({ ...observation, projectId, sourceDetail: 'hook' });
-
-      // Shadow mode: Formation Pipeline metrics (fire-and-forget, never blocks)
-      try {
-        const { runFormation } = await import('../memory/formation/index.js');
-        const formationMode = (process.env.MEMORIX_FORMATION_MODE as 'shadow' | 'active' | 'fallback') || 'shadow';
-        const samplingRate = parseFloat(process.env.MEMORIX_FORMATION_HOOKS_SAMPLING_RATE || '0.1');
-        const shouldSample = Math.random() < samplingRate;
-
-        if (shouldSample) {
-          const { withFreshIndex } = await import('../memory/freshness.js');
-          const { getAllObservations } = await import('../memory/observations.js');
-          await withFreshIndex(() => getAllObservations());
-        }
-
-        // In hooks, shadow mode by default for performance
-        // Sampling rate controls how often we run full resolve (expensive)
-        const searchFn = shouldSample
-          ? async (q: string, limit: number, pid: string) => {
-              const { compactSearch, compactDetail } = await import('../compact/engine.js');
-              const result = await compactSearch({ query: q, limit, projectId: pid, status: 'active' });
-              if (result.entries.length === 0) return [];
-              const details = await compactDetail(result.entries.map(e => e.id));
-              return details.documents.map((d, i) => ({
-                id: Number(d.id.replace('obs-', '')),
-                observationId: d.observationId,
-                title: d.title,
-                narrative: d.narrative,
-                facts: d.facts,
-                entityName: d.entityName,
-                type: d.type,
-                score: result.entries[i]?.score ?? 0,
-              }));
-            }
-          : async () => []; // Skip search for speed (shadow mode)
-
-        const getObsFn = shouldSample
-          ? (id: number) => {
-              const { getObservation } = require('../memory/observations.js');
-              const o = getObservation(id);
-              if (!o) return null;
-              return {
-                id: o.id,
-                entityName: o.entityName,
-                type: o.type,
-                title: o.title,
-                narrative: o.narrative,
-                facts: o.facts,
-                topicKey: o.topicKey,
-              };
-            }
-          : () => null;
-
-        const getEntityNamesFn = shouldSample
-          ? () => {
-              const { graphManager } = require('../memory/graph.js');
-              return graphManager.getEntityNames();
-            }
-          : () => [];
-
-        runFormation({
-          entityName: observation.entityName,
-          type: observation.type,
-          title: observation.title,
-          narrative: observation.narrative,
-          facts: observation.facts,
-          projectId,
-          source: 'hook' as const,
-        }, {
-          mode: formationMode,
-          useLLM: false,
-          minValueScore: 0.3,
-          hooksSamplingRate: samplingRate,
-          searchMemories: searchFn,
-          getObservation: getObsFn,
-          getEntityNames: getEntityNamesFn,
-        }).catch(() => {});
-      } catch { /* Formation is optional — never break hooks */ }
-
-      // Feedback: tell the agent what was saved
-      const emoji = TYPE_EMOJI[observation.type] ?? '[PLAN]';
-      output.systemMessage = (output.systemMessage ?? '') +
-        `\n${emoji} Memorix saved: ${observation.title} [${observation.type}]`;
+      // Automatic capture is deliberately quiet. Candidate state and later
+      // qualification are visible through Memorix inspection, not injected as
+      // a stream of status messages into the host agent's context.
     } catch (storeErr) {
       // Diagnostic log — hooks must never break the agent, but silent
       // swallow makes end-to-end debugging impossible.
@@ -685,6 +687,11 @@ export async function runHook(agentOverride?: string, eventOverride?: string): P
     }
   }
 
+  // A candidate must be durable before a Code Memory refresh can qualify it.
+  // Keep direct handleHookEvent() backward-compatible, but make the real CLI
+  // hook path explicitly capture first and schedule second.
+  await queueCodegraphRefreshForMutation(input);
+
   // Build hookSpecificOutput — Claude Code only supports it for 3 event types:
   //   PreToolUse, UserPromptSubmit, PostToolUse
   // Other events (SessionStart, Stop, PreCompact) must NOT include hookSpecificOutput.