memorix 1.2.0 → 1.2.2

package/src/cli/commands/cleanup.ts

@@ -19,6 +19,7 @@ import { detectProject } from '../../project/detector.js';
 import { getProjectDataDir } from '../../store/persistence.js';
 import type { ObservationStore } from '../../store/obs-store.js';
 import { getObservationStore, initObservationStore } from '../../store/obs-store.js';
+import { filterReadableObservations } from '../../memory/visibility.js';
 
 /** Patterns that indicate auto-generated, low-value observations */
 const LOW_QUALITY_PATTERNS = [
@@ -148,7 +149,10 @@ export default defineCommand({
         const dataDir = await getProjectDataDir(projectId);
         await initObservationStore(dataDir);
         const store = getObservationStore();
-        const projectObs = await store.loadByProject(projectId, { status: 'active' }) as Array<{
+        const projectObs = filterReadableObservations(
+            await store.loadByProject(projectId, { status: 'active' }),
+            { projectId },
+        ) as Array<{
             id?: number;
             type?: string;
             title?: string;

package/src/cli/commands/codegraph.ts

@@ -3,12 +3,13 @@ import { CodeGraphStore } from '../../codegraph/store.js';
 import { refreshProjectLite } from '../../codegraph/lite-provider.js';
 import { assembleContextPackForTask, attachTaskWorkset, buildContextPackPrompt } from '../../codegraph/context-pack.js';
 import { backfillMissingObservationCodeRefs } from '../../codegraph/binder.js';
-import { collectCurrentProjectFacts } from '../../codegraph/current-facts.js';
+import { collectCurrentProjectFacts, formatGitFact } from '../../codegraph/current-facts.js';
 import { resolveTaskLens } from '../../codegraph/task-lens.js';
 import { getExternalCodeGraphContext, inspectExternalCodeGraph } from '../../codegraph/external-provider.js';
 import type { CodeGraphProviderQuality } from '../../codegraph/types.js';
 import { getResolvedConfig } from '../../config/resolved-config.js';
 import { getAllObservations } from '../../memory/observations.js';
+import { filterReadableObservations } from '../../memory/visibility.js';
 import { emitError, emitResult, getCliProjectContext, parsePositiveInt } from './operator-shared.js';
 
 function formatSnapshotStatus(status: ReturnType<CodeGraphStore['status']>): string[] {
@@ -71,8 +72,7 @@ function compactFacts(project: { rootPath: string }): { facts: string[]; dirty:
     facts.push('Latest changelog: ' + current.latestChangelog.version
       + (current.latestChangelog.date ? ' (' + current.latestChangelog.date + ')' : ''));
   }
-  facts.push('Git: ' + (current.git.branch ? 'branch ' + current.git.branch + ', ' : '')
-    + (current.git.dirty ? 'dirty worktree' : 'clean worktree'));
+  facts.push(formatGitFact(current.git));
   return { facts, dirty: current.git.dirty };
 }
 
@@ -93,7 +93,7 @@ export default defineCommand({
     const asJson = !!args.json;
 
     try {
-      const { project, dataDir } = await getCliProjectContext();
+      const { project, dataDir, reader } = await getCliProjectContext();
       const store = new CodeGraphStore();
       await store.init(dataDir);
       const explicitAction = Boolean(positional[0] || (args.action as string | undefined));
@@ -126,13 +126,21 @@ export default defineCommand({
           const activeObservations = getAllObservations()
             .filter(obs => obs.projectId === project.id && (obs.status ?? 'active') === 'active');
           const backfill = await backfillMissingObservationCodeRefs(store, activeObservations);
-          const { enqueueClaimRequalification } = await import('../../runtime/lifecycle.js');
+          const {
+            enqueueClaimRequalification,
+            enqueueObservationQualification,
+          } = await import('../../runtime/lifecycle.js');
           enqueueClaimRequalification({
             dataDir,
             projectId: project.id,
             source: 'manual-codegraph-refresh',
             snapshotId: refresh.snapshot.id,
           });
+          enqueueObservationQualification({
+            dataDir,
+            projectId: project.id,
+            source: 'manual-codegraph-refresh',
+          });
           const status = store.status(project.id);
           const providerQuality = await inspectExternalCodeGraph({
             projectRoot: project.rootPath,
@@ -161,9 +169,10 @@ export default defineCommand({
             return;
           }
           const limit = parsePositiveInt(args.limit as string | undefined, 20);
-          const observations = getAllObservations()
-            .filter(obs => obs.projectId === project.id && (obs.status ?? 'active') === 'active')
-            .reverse();
+          const observations = filterReadableObservations(
+            getAllObservations().filter(obs => obs.projectId === project.id && (obs.status ?? 'active') === 'active'),
+            reader,
+          ).reverse();
           const basePack = assembleContextPackForTask({
             store,
             projectId: project.id,

package/src/cli/commands/context.ts

@@ -6,6 +6,7 @@ import {
   type AutoContextRefreshMode,
 } from '../../codegraph/auto-context.js';
 import { getAllObservations } from '../../memory/observations.js';
+import { filterReadableObservations } from '../../memory/visibility.js';
 import { emitError, emitResult, getCliProjectContext } from './operator-shared.js';
 
 function coerceRefreshMode(input?: string): AutoContextRefreshMode {
@@ -28,11 +29,11 @@ export default defineCommand({
     const asJson = !!args.json;
 
     try {
-      const { project, dataDir } = await getCliProjectContext();
+      const { project, dataDir, reader } = await getCliProjectContext();
       const context = await buildAutoProjectContext({
         project,
         dataDir,
-        observations: getAllObservations(),
+        observations: filterReadableObservations(getAllObservations(), reader),
         task: args.task as string | undefined,
         refresh: coerceRefreshMode(args.refresh as string | undefined),
       });

package/src/cli/commands/doctor.ts

@@ -257,8 +257,10 @@ export default defineCommand({
         await initObservationStore(dataDir);
         const store = getObservationStore();
         backendName = store.getBackendName();
-        const obs = await store.loadAll();
-        projectObservations = obs.filter((o: any) => o.projectId === projectId);
+        const { filterReadableObservations } = await import('../../memory/visibility.js');
+        projectObservations = projectId
+          ? filterReadableObservations(await store.loadAll(), { projectId })
+          : [];
         obsCount = projectObservations.length;
         activeCount = projectObservations.filter((o: any) => (o.status ?? 'active') === 'active').length;
         ranCount = projectObservations.filter((o: any) => /^Ran:\s/i.test(o.title ?? '')).length;

package/src/cli/commands/explain.ts

@@ -1,7 +1,9 @@
 import { defineCommand } from 'citty';
 import { buildAutoProjectContext, type AutoContextRefreshMode } from '../../codegraph/auto-context.js';
 import { formatProjectContextExplain } from '../../codegraph/project-context.js';
+import { formatContextReceipt } from '../../knowledge/context-assembly.js';
 import { getAllObservations } from '../../memory/observations.js';
+import { filterReadableObservations } from '../../memory/visibility.js';
 import { emitError, emitResult, getCliProjectContext } from './operator-shared.js';
 
 function coerceRefreshMode(input?: string): AutoContextRefreshMode {
@@ -23,15 +25,19 @@ export default defineCommand({
     const asJson = !!args.json;
 
     try {
-      const { project, dataDir } = await getCliProjectContext();
+      const { project, dataDir, reader } = await getCliProjectContext();
       const context = await buildAutoProjectContext({
         project,
         dataDir,
-        observations: getAllObservations(),
+        observations: filterReadableObservations(getAllObservations(), reader),
         refresh: coerceRefreshMode(args.refresh as string | undefined),
       });
 
-      emitResult({ project, explain: context.explain, refresh: context.refresh }, formatProjectContextExplain(context.explain), asJson);
+      emitResult(
+        { project, explain: context.explain, receipt: context.workset.receipt, refresh: context.refresh },
+        formatProjectContextExplain(context.explain) + '\n\n' + formatContextReceipt(context.workset.receipt),
+        asJson,
+      );
     } catch (error) {
       emitError(error instanceof Error ? error.message : String(error), asJson);
     }

package/src/cli/commands/formation.ts

@@ -1,48 +1,48 @@
-import { defineCommand } from 'citty';
-import { getBeforeAfterMetrics, getMetricsSummary } from '../../memory/formation/index.js';
-import { emitError, emitResult } from './operator-shared.js';
-
-export default defineCommand({
-  meta: {
-    name: 'formation',
-    description: 'Inspect Memory Formation Pipeline runtime metrics',
-  },
-  args: {
-    json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
-  },
-  run: async ({ args }) => {
-    const action = (args._ as string[])?.[0] || '';
-    const asJson = !!args.json;
-
-    try {
-      switch (action) {
-        case 'metrics': {
-          const summary = getMetricsSummary();
-          const beforeAfter = getBeforeAfterMetrics();
-          emitResult(
-            { summary, beforeAfter },
-            summary.total === 0
-              ? 'Formation Pipeline: No metrics collected yet.'
-              : [
-                  'Formation Pipeline Metrics',
-                  `- Total observations processed: ${summary.total}`,
-                  `- Average value score: ${summary.avgValueScore.toFixed(3)}`,
-                  `- Average processing time: ${summary.avgDurationMs.toFixed(1)}ms`,
-                ].join('\n'),
-            asJson,
-          );
-          return;
-        }
-
-        default:
-          console.log('Memorix Formation Commands');
-          console.log('');
-          console.log('Usage:');
-          console.log('  memorix formation metrics');
-      }
-    } catch (error) {
-      emitError(error instanceof Error ? error.message : String(error), asJson);
-    }
-  },
-});
-
+import { defineCommand } from 'citty';
+import { getBeforeAfterMetrics, getMetricsSummary } from '../../memory/formation/index.js';
+import { emitError, emitResult } from './operator-shared.js';
+
+export default defineCommand({
+  meta: {
+    name: 'formation',
+    description: 'Inspect Memory Formation Pipeline runtime metrics',
+  },
+  args: {
+    json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+  },
+  run: async ({ args }) => {
+    const action = (args._ as string[])?.[0] || '';
+    const asJson = !!args.json;
+
+    try {
+      switch (action) {
+        case 'metrics': {
+          const summary = getMetricsSummary();
+          const beforeAfter = getBeforeAfterMetrics();
+          emitResult(
+            { summary, beforeAfter },
+            summary.total === 0
+              ? 'Formation Pipeline: No metrics collected yet.'
+              : [
+                  'Formation Pipeline Metrics',
+                  `- Total observations processed: ${summary.total}`,
+                  `- Average value score: ${summary.avgValueScore.toFixed(3)}`,
+                  `- Average processing time: ${summary.avgDurationMs.toFixed(1)}ms`,
+                ].join('\n'),
+            asJson,
+          );
+          return;
+        }
+
+        default:
+          console.log('Memorix Formation Commands');
+          console.log('');
+          console.log('Usage:');
+          console.log('  memorix formation metrics');
+      }
+    } catch (error) {
+      emitError(error instanceof Error ? error.message : String(error), asJson);
+    }
+  },
+});
+

package/src/cli/commands/git-hook-install.ts

@@ -1,111 +1,111 @@
-/**
- * CLI Command: memorix git-hook install
- *
- * Installs a git post-commit hook that automatically ingests commits as memories.
- * This is the Git→Memory automation — every commit becomes a searchable memory.
- *
- * Cross-platform: generates both bash (Unix) and PowerShell (Windows) hooks.
- */
-
-import { defineCommand } from 'citty';
-import * as p from '@clack/prompts';
-import { existsSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
-import { ensureHooksDir } from '../../git/hooks-path.js';
-
-const HOOK_MARKER = '# [memorix-git-hook]';
-
-export default defineCommand({
-  meta: {
-    name: 'git-hook-install',
-    description: 'Install git post-commit hook for automatic memory capture',
-  },
-  args: {
-    cwd: {
-      type: 'string',
-      description: 'Project directory (default: current directory)',
-      required: false,
-    },
-    force: {
-      type: 'boolean',
-      description: 'Overwrite existing hook without asking',
-      required: false,
-    },
-  },
-  run: async ({ args }) => {
-    const projectDir = args.cwd || process.cwd();
-
-    p.intro('Install Git post-commit hook');
-
-    // 1. Resolve git hooks directory (handles normal repos and worktrees)
-    const resolved = ensureHooksDir(projectDir);
-    if (!resolved) {
-      p.log.error(`No .git found in ${projectDir} (checked both directory and worktree file)`);
-      p.outro('Run this command from a git repository root.');
-      return;
-    }
-
-    const { hookPath } = resolved;
-
-    // 3. Check for existing hook
-    if (existsSync(hookPath)) {
-      const existing = readFileSync(hookPath, 'utf-8');
-
-      if (existing.includes(HOOK_MARKER)) {
-        p.log.warn('Memorix git hook is already installed.');
-        p.outro('Use `memorix git-hook uninstall` to remove it first.');
-        return;
-      }
-
-      // Existing non-memorix hook — ask to append
-      if (!args.force) {
-        const action = await p.select({
-          message: 'A post-commit hook already exists. What would you like to do?',
-          options: [
-            { value: 'append', label: 'Append', hint: 'Add memorix hook after existing content' },
-            { value: 'skip', label: 'Skip', hint: 'Do not modify the existing hook' },
-          ],
-        });
-
-        if (p.isCancel(action) || action === 'skip') {
-          p.outro('Installation cancelled.');
-          return;
-        }
-      }
-
-      // Append to existing hook
-      const appended = existing.trimEnd() + '\n\n' + generateHookScript();
-      writeFileSync(hookPath, appended, 'utf-8');
-      try { chmodSync(hookPath, 0o755); } catch { /* Windows doesn't need chmod */ }
-
-      p.log.success('Memorix hook appended to existing post-commit hook.');
-    } else {
-      // Create new hook
-      const script = '#!/bin/sh\n' + generateHookScript();
-      writeFileSync(hookPath, script, 'utf-8');
-      try { chmodSync(hookPath, 0o755); } catch { /* Windows doesn't need chmod */ }
-
-      p.log.success('Git post-commit hook installed.');
-    }
-
-    p.log.info(`Hook path: ${hookPath}`);
-    p.log.info('Every commit will now be automatically captured as a memory.');
-    p.log.info('Memories are tagged with source="git" and include the commit hash.');
-    p.outro('Done! Try making a commit to see it in action.');
-  },
-});
-
-/**
- * Generate the hook script content.
- * Uses `memorix ingest commit --auto` for non-interactive ingest.
- * Runs in background to not block the commit.
- */
-function generateHookScript(): string {
-  return `${HOOK_MARKER}
-# Memorix: Auto-ingest git commits as memories
-# Runs in background — does not block your commit workflow.
-# To remove: memorix git-hook uninstall
-if command -v memorix >/dev/null 2>&1; then
-  memorix ingest commit --auto >/dev/null 2>&1 &
-fi
-`;
-}
+/**
+ * CLI Command: memorix git-hook install
+ *
+ * Installs a git post-commit hook that automatically ingests commits as memories.
+ * This is the Git→Memory automation — every commit becomes a searchable memory.
+ *
+ * Cross-platform: generates both bash (Unix) and PowerShell (Windows) hooks.
+ */
+
+import { defineCommand } from 'citty';
+import * as p from '@clack/prompts';
+import { existsSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { ensureHooksDir } from '../../git/hooks-path.js';
+
+const HOOK_MARKER = '# [memorix-git-hook]';
+
+export default defineCommand({
+  meta: {
+    name: 'git-hook-install',
+    description: 'Install git post-commit hook for automatic memory capture',
+  },
+  args: {
+    cwd: {
+      type: 'string',
+      description: 'Project directory (default: current directory)',
+      required: false,
+    },
+    force: {
+      type: 'boolean',
+      description: 'Overwrite existing hook without asking',
+      required: false,
+    },
+  },
+  run: async ({ args }) => {
+    const projectDir = args.cwd || process.cwd();
+
+    p.intro('Install Git post-commit hook');
+
+    // 1. Resolve git hooks directory (handles normal repos and worktrees)
+    const resolved = ensureHooksDir(projectDir);
+    if (!resolved) {
+      p.log.error(`No .git found in ${projectDir} (checked both directory and worktree file)`);
+      p.outro('Run this command from a git repository root.');
+      return;
+    }
+
+    const { hookPath } = resolved;
+
+    // 3. Check for existing hook
+    if (existsSync(hookPath)) {
+      const existing = readFileSync(hookPath, 'utf-8');
+
+      if (existing.includes(HOOK_MARKER)) {
+        p.log.warn('Memorix git hook is already installed.');
+        p.outro('Use `memorix git-hook uninstall` to remove it first.');
+        return;
+      }
+
+      // Existing non-memorix hook — ask to append
+      if (!args.force) {
+        const action = await p.select({
+          message: 'A post-commit hook already exists. What would you like to do?',
+          options: [
+            { value: 'append', label: 'Append', hint: 'Add memorix hook after existing content' },
+            { value: 'skip', label: 'Skip', hint: 'Do not modify the existing hook' },
+          ],
+        });
+
+        if (p.isCancel(action) || action === 'skip') {
+          p.outro('Installation cancelled.');
+          return;
+        }
+      }
+
+      // Append to existing hook
+      const appended = existing.trimEnd() + '\n\n' + generateHookScript();
+      writeFileSync(hookPath, appended, 'utf-8');
+      try { chmodSync(hookPath, 0o755); } catch { /* Windows doesn't need chmod */ }
+
+      p.log.success('Memorix hook appended to existing post-commit hook.');
+    } else {
+      // Create new hook
+      const script = '#!/bin/sh\n' + generateHookScript();
+      writeFileSync(hookPath, script, 'utf-8');
+      try { chmodSync(hookPath, 0o755); } catch { /* Windows doesn't need chmod */ }
+
+      p.log.success('Git post-commit hook installed.');
+    }
+
+    p.log.info(`Hook path: ${hookPath}`);
+    p.log.info('Every commit will now be automatically captured as a memory.');
+    p.log.info('Memories are tagged with source="git" and include the commit hash.');
+    p.outro('Done! Try making a commit to see it in action.');
+  },
+});
+
+/**
+ * Generate the hook script content.
+ * Uses `memorix ingest commit --auto` for non-interactive ingest.
+ * Runs in background to not block the commit.
+ */
+function generateHookScript(): string {
+  return `${HOOK_MARKER}
+# Memorix: Auto-ingest git commits as memories
+# Runs in background — does not block your commit workflow.
+# To remove: memorix git-hook uninstall
+if command -v memorix >/dev/null 2>&1; then
+  memorix ingest commit --auto >/dev/null 2>&1 &
+fi
+`;
+}

package/src/cli/commands/handoff.ts

@@ -1,66 +1,80 @@
-import { defineCommand } from 'citty';
-import { storeObservation } from '../../memory/observations.js';
-import { createHandoffArtifact } from '../../team/handoff.js';
-import { emitError, emitResult, getCliProjectContext, parseCsvList, shortId } from './operator-shared.js';
-
-export default defineCommand({
-  meta: {
-    name: 'handoff',
-    description: 'Create structured handoff artifacts between agents',
-  },
-  args: {
-    fromAgentId: { type: 'string', description: 'Sender agent ID' },
-    toAgentId: { type: 'string', description: 'Optional recipient agent ID' },
-    taskId: { type: 'string', description: 'Optional related task ID' },
-    summary: { type: 'string', description: 'Human-readable summary of the handoff' },
-    context: { type: 'string', description: 'Detailed machine-readable context for the next agent' },
-    filesModified: { type: 'string', description: 'Comma-separated file list' },
-    concepts: { type: 'string', description: 'Comma-separated discoverability concepts' },
-    json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
-  },
-  run: async ({ args }) => {
-    const action = (args._ as string[])?.[0] || '';
-    const asJson = !!args.json;
-
-    try {
-      const { project, teamStore } = await getCliProjectContext();
-
-      switch (action) {
-        case 'send': {
-          if (!args.fromAgentId || !args.summary || !args.context) {
-            emitError('fromAgentId, summary, and context are required for "memorix handoff send"', asJson);
+import { defineCommand } from 'citty';
+import { storeObservation } from '../../memory/observations.js';
+import { createHandoffArtifact } from '../../team/handoff.js';
+import { emitError, emitResult, getCliProjectContext, parseCsvList, resolveCliActorId, shortId } from './operator-shared.js';
+
+export default defineCommand({
+  meta: {
+    name: 'handoff',
+    description: 'Create structured handoff artifacts between agents',
+  },
+  args: {
+    fromAgentId: { type: 'string', description: 'Sender agent ID' },
+    toAgentId: { type: 'string', description: 'Optional recipient agent ID' },
+    taskId: { type: 'string', description: 'Optional related task ID' },
+    summary: { type: 'string', description: 'Human-readable summary of the handoff' },
+    context: { type: 'string', description: 'Detailed machine-readable context for the next agent' },
+    filesModified: { type: 'string', description: 'Comma-separated file list' },
+    concepts: { type: 'string', description: 'Comma-separated discoverability concepts' },
+    json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+  },
+  run: async ({ args }) => {
+    const action = (args._ as string[])?.[0] || '';
+    const asJson = !!args.json;
+
+    try {
+      const { project, teamStore, identity } = await getCliProjectContext();
+      const fromAgentId = resolveCliActorId(args.fromAgentId, identity, 'fromAgentId');
+
+      switch (action) {
+        case 'send': {
+          if (!fromAgentId || !args.summary || !args.context) {
+            emitError('summary, context, and an active CLI identity or fromAgentId are required for "memorix handoff send"', asJson);
             return;
           }
+          const sender = teamStore.getAgent(fromAgentId);
+          if (!sender || sender.project_id !== project.id || sender.status !== 'active') {
+            emitError('The handoff sender must be an active coordination member of this project.', asJson);
+            return;
+          }
+          const toAgentId = (args.toAgentId as string | undefined)?.trim();
+          if (toAgentId) {
+            const recipient = teamStore.getAgent(toAgentId);
+            if (!recipient || recipient.project_id !== project.id || recipient.status !== 'active') {
+              emitError('The handoff recipient must be an active coordination member of this project.', asJson);
+              return;
+            }
+          }
           const result = await createHandoffArtifact(
             {
               projectId: project.id,
-              fromAgentId: args.fromAgentId as string,
-              toAgentId: args.toAgentId as string | undefined,
-              taskId: args.taskId as string | undefined,
-              summary: args.summary as string,
-              context: args.context as string,
-              filesModified: parseCsvList(args.filesModified as string | undefined),
-              concepts: parseCsvList(args.concepts as string | undefined),
-            },
-            storeObservation,
-            teamStore,
-          );
-          emitResult(
-            { project, handoff: result },
-            `Handoff created: observation #${result.observationId} from ${shortId(result.fromAgentId)}${result.toAgentId ? ` to ${shortId(result.toAgentId)}` : ' (broadcast)'}`,
-            asJson,
-          );
-          return;
-        }
-
-        default:
-          console.log('Memorix Handoff Commands');
-          console.log('');
-          console.log('Usage:');
-          console.log('  memorix handoff send --fromAgentId <id> --summary "..." --context "..." [--toAgentId <id>] [--taskId <id>]');
-      }
-    } catch (error) {
-      emitError(error instanceof Error ? error.message : String(error), asJson);
-    }
-  },
-});
+              fromAgentId,
+              toAgentId,
+              taskId: args.taskId as string | undefined,
+              summary: args.summary as string,
+              context: args.context as string,
+              filesModified: parseCsvList(args.filesModified as string | undefined),
+              concepts: parseCsvList(args.concepts as string | undefined),
+            },
+            storeObservation,
+            teamStore,
+          );
+          emitResult(
+            { project, handoff: result },
+            `Handoff created: observation #${result.observationId} from ${shortId(result.fromAgentId)}${result.toAgentId ? ` to ${shortId(result.toAgentId)}` : ' (broadcast)'}`,
+            asJson,
+          );
+          return;
+        }
+
+        default:
+          console.log('Memorix Handoff Commands');
+          console.log('');
+          console.log('Usage:');
+          console.log('  memorix handoff send --summary "..." --context "..." [--fromAgentId <id>] [--toAgentId <id>] [--taskId <id>]');
+      }
+    } catch (error) {
+      emitError(error instanceof Error ? error.message : String(error), asJson);
+    }
+  },
+});