memorix 1.5.1 → 1.6.0

package/docs/DEVELOPMENT.md

@@ -326,9 +326,11 @@ Notes:
 - `server.json` is the official MCP Registry record. Keep it synchronized with
   `package.json` by running `npm run sync:mcp-registry`; verify it with
   `npm run check:mcp-registry` before a release.
-- The GitHub publish workflow publishes npm first, then uses GitHub OIDC to
-  publish the same verified version to the official MCP Registry. It does not
-  require a Registry token or private key in repository secrets.
+- The GitHub publish workflow can publish npm first, then uses GitHub OIDC to
+  publish the same verified version to the official MCP Registry. When npm was
+  already published manually, run the workflow with `publish_npm=false` to
+  publish only the Registry record. It does not require a Registry token or
+  private key in repository secrets.
 - `@memorix/ai`, `@memorix/agent-core`, `@memorix/tui`, and `@memorix/memcode` are internal workspaces. Their code is bundled into the root `memorix` distribution and they must stay `private` unless the project deliberately establishes an owned npm scope and a separate package-support contract.
 - npm publish is usually manual, especially when 2FA is enabled
 - GitHub release automation should not be treated as a substitute for manual runtime validation

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "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.5.1",
+  "version": "1.6.0",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

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

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Local-first project memory for CodeBuddy Code and other coding agents.",
   "author": {
     "name": "AVIDS2",

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

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "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.5.1",
+  "version": "1.6.0",
   "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.5.1",
+  "version": "1.6.0",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "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.5.1",
+  "version": "1.6.0",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

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

package/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/AVIDS2/memorix",
     "source": "github"
   },
-  "version": "1.5.1",
+  "version": "1.6.0",
   "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.5.1",
+      "version": "1.6.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/audit/index.ts

@@ -1,156 +1,156 @@
-/**
- * Audit Module - Track Memorix-written files
- *
- * Records all files written by Memorix to distinguish them from
- * project-native files. Provides audit trail for cleanup and rollback.
- */
-
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { homedir } from 'node:os';
-
-function getAuditFilePath(): string {
-  return process.env.MEMORIX_AUDIT_FILE || path.join(homedir(), '.memorix', 'audit.json');
-}
-
-export interface AuditEntry {
-  type: 'hook' | 'rule' | 'other';
-  agent?: string;
-  path: string;
-  createdAt: string;
-}
-
-export interface ProjectAudit {
-  projectRoot: string;
-  installedAt: string;
-  entries: AuditEntry[];
-}
-
-export interface AuditData {
-  version: string;
-  projects: Record<string, ProjectAudit>;
-}
-
-/**
- * Load audit data from disk.
- */
-export async function loadAudit(): Promise<AuditData> {
-  try {
-    const content = await fs.readFile(getAuditFilePath(), 'utf-8');
-    return JSON.parse(content) as AuditData;
-  } catch {
-    // No audit file yet
-    return {
-      version: '1.0.0',
-      projects: {},
-    };
-  }
-}
-
-/**
- * Save audit data to disk.
- */
-export async function saveAudit(data: AuditData): Promise<void> {
-  const auditFile = getAuditFilePath();
-  const dir = path.dirname(auditFile);
-  await fs.mkdir(dir, { recursive: true });
-  await fs.writeFile(auditFile, JSON.stringify(data, null, 2), 'utf-8');
-}
-
-/**
- * Get project ID from project root via .git detection.
- */
-export function getProjectId(projectRoot: string): string {
-  try {
-    const { detectProject } = require('../project/detector.js');
-    const project = detectProject(projectRoot);
-    if (project) return project.id;
-  } catch { /* fallback below */ }
-  const normalized = projectRoot.replace(/\\/g, '/');
-  return `untracked/${normalized}`;
-}
-
-/**
- * Record a file written by Memorix.
- */
-export async function recordFile(
-  projectRoot: string,
-  type: AuditEntry['type'],
-  filePath: string,
-  agent?: string,
-): Promise<void> {
-  const data = await loadAudit();
-  const projectId = getProjectId(projectRoot);
-
-  if (!data.projects[projectId]) {
-    data.projects[projectId] = {
-      projectRoot,
-      installedAt: new Date().toISOString(),
-      entries: [],
-    };
-  }
-
-  // Check if entry already exists
-  const existingIndex = data.projects[projectId].entries.findIndex(
-    (e) => e.path === filePath
-  );
-
-  if (existingIndex === -1) {
-    data.projects[projectId].entries.push({
-      type,
-      agent,
-      path: filePath,
-      createdAt: new Date().toISOString(),
-    });
-  }
-
-  await saveAudit(data);
-}
-
-/**
- * Get all files written by Memorix for a project.
- */
-export async function getProjectFiles(projectRoot: string): Promise<AuditEntry[]> {
-  const data = await loadAudit();
-  const projectId = getProjectId(projectRoot);
-  return data.projects[projectId]?.entries || [];
-}
-
-/**
- * Remove a file from audit (when uninstalled).
- */
-export async function removeFile(projectRoot: string, filePath: string): Promise<void> {
-  const data = await loadAudit();
-  const projectId = getProjectId(projectRoot);
-
-  if (!data.projects[projectId]) return;
-
-  data.projects[projectId].entries = data.projects[projectId].entries.filter(
-    (e) => e.path !== filePath
-  );
-
-  // If no entries left, remove the project
-  if (data.projects[projectId].entries.length === 0) {
-    delete data.projects[projectId];
-  }
-
-  await saveAudit(data);
-}
-
-/**
- * Get all audit entries across all projects.
- */
-export async function getAllAuditEntries(): Promise<
-  Array<{ projectId: string; entry: AuditEntry }>
-> {
-  const data = await loadAudit();
-  const entries: Array<{ projectId: string; entry: AuditEntry }> = [];
-
-  for (const [projectId, project] of Object.entries(data.projects)) {
-    for (const entry of project.entries) {
-      entries.push({ projectId, entry });
-    }
-  }
-
-  return entries;
-}
+/**
+ * Audit Module - Track Memorix-written files
+ *
+ * Records all files written by Memorix to distinguish them from
+ * project-native files. Provides audit trail for cleanup and rollback.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { homedir } from 'node:os';
+
+function getAuditFilePath(): string {
+  return process.env.MEMORIX_AUDIT_FILE || path.join(homedir(), '.memorix', 'audit.json');
+}
+
+export interface AuditEntry {
+  type: 'hook' | 'rule' | 'other';
+  agent?: string;
+  path: string;
+  createdAt: string;
+}
+
+export interface ProjectAudit {
+  projectRoot: string;
+  installedAt: string;
+  entries: AuditEntry[];
+}
+
+export interface AuditData {
+  version: string;
+  projects: Record<string, ProjectAudit>;
+}
+
+/**
+ * Load audit data from disk.
+ */
+export async function loadAudit(): Promise<AuditData> {
+  try {
+    const content = await fs.readFile(getAuditFilePath(), 'utf-8');
+    return JSON.parse(content) as AuditData;
+  } catch {
+    // No audit file yet
+    return {
+      version: '1.0.0',
+      projects: {},
+    };
+  }
+}
+
+/**
+ * Save audit data to disk.
+ */
+export async function saveAudit(data: AuditData): Promise<void> {
+  const auditFile = getAuditFilePath();
+  const dir = path.dirname(auditFile);
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(auditFile, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+/**
+ * Get project ID from project root via .git detection.
+ */
+export function getProjectId(projectRoot: string): string {
+  try {
+    const { detectProject } = require('../project/detector.js');
+    const project = detectProject(projectRoot);
+    if (project) return project.id;
+  } catch { /* fallback below */ }
+  const normalized = projectRoot.replace(/\\/g, '/');
+  return `untracked/${normalized}`;
+}
+
+/**
+ * Record a file written by Memorix.
+ */
+export async function recordFile(
+  projectRoot: string,
+  type: AuditEntry['type'],
+  filePath: string,
+  agent?: string,
+): Promise<void> {
+  const data = await loadAudit();
+  const projectId = getProjectId(projectRoot);
+
+  if (!data.projects[projectId]) {
+    data.projects[projectId] = {
+      projectRoot,
+      installedAt: new Date().toISOString(),
+      entries: [],
+    };
+  }
+
+  // Check if entry already exists
+  const existingIndex = data.projects[projectId].entries.findIndex(
+    (e) => e.path === filePath
+  );
+
+  if (existingIndex === -1) {
+    data.projects[projectId].entries.push({
+      type,
+      agent,
+      path: filePath,
+      createdAt: new Date().toISOString(),
+    });
+  }
+
+  await saveAudit(data);
+}
+
+/**
+ * Get all files written by Memorix for a project.
+ */
+export async function getProjectFiles(projectRoot: string): Promise<AuditEntry[]> {
+  const data = await loadAudit();
+  const projectId = getProjectId(projectRoot);
+  return data.projects[projectId]?.entries || [];
+}
+
+/**
+ * Remove a file from audit (when uninstalled).
+ */
+export async function removeFile(projectRoot: string, filePath: string): Promise<void> {
+  const data = await loadAudit();
+  const projectId = getProjectId(projectRoot);
+
+  if (!data.projects[projectId]) return;
+
+  data.projects[projectId].entries = data.projects[projectId].entries.filter(
+    (e) => e.path !== filePath
+  );
+
+  // If no entries left, remove the project
+  if (data.projects[projectId].entries.length === 0) {
+    delete data.projects[projectId];
+  }
+
+  await saveAudit(data);
+}
+
+/**
+ * Get all audit entries across all projects.
+ */
+export async function getAllAuditEntries(): Promise<
+  Array<{ projectId: string; entry: AuditEntry }>
+> {
+  const data = await loadAudit();
+  const entries: Array<{ projectId: string; entry: AuditEntry }> = [];
+
+  for (const [projectId, project] of Object.entries(data.projects)) {
+    for (const entry of project.entries) {
+      entries.push({ projectId, entry });
+    }
+  }
+
+  return entries;
+}

package/src/cli/commands/codegraph.ts

@@ -5,11 +5,14 @@ import { assembleContextPackForTask, attachTaskWorkset, buildContextPackPrompt }
 import { backfillMissingObservationCodeRefs } from '../../codegraph/binder.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 { getExternalCodeGraphContext, inspectExternalCodeGraph, runExternalCodeGraphLifecycle } from '../../codegraph/external-provider.js';
 import type { CodeGraphProviderQuality } from '../../codegraph/types.js';
 import { getResolvedConfig } from '../../config/resolved-config.js';
+import { buildBoundedContextReceipt } from '../../knowledge/context-receipt.js';
+import { WORKFLOW_AGENT_TARGETS } from '../../knowledge/workflows.js';
 import { getAllObservations } from '../../memory/observations.js';
 import { filterReadableObservations } from '../../memory/visibility.js';
+import type { AgentTarget } from '../../types.js';
 import { emitError, emitResult, getCliProjectContext, parsePositiveInt } from './operator-shared.js';
 
 function formatSnapshotStatus(status: ReturnType<CodeGraphStore['status']>): string[] {
@@ -48,6 +51,7 @@ function formatStatus(status: ReturnType<CodeGraphStore['status']>, quality?: Co
         `- Persistent provider: ${status.provider} (heuristic local index)`,
         `- External semantic CodeGraph: ${quality.external.state}`
           + (quality.external.reason ? ` (${quality.external.reason})` : ''),
+        `- Task-scoped provider: ${quality.selected} (${quality.selectedQuality})`,
       ]
       : []),
   ].join('\n');
@@ -57,6 +61,8 @@ function formatUsageHint(): string {
   return [
     'Usage:',
     '  memorix codegraph refresh',
+    '  memorix codegraph init       # explicit local CodeGraph initialization',
+    '  memorix codegraph sync       # explicit local CodeGraph synchronization',
     '  memorix codegraph status --json',
     '  memorix codegraph diff [--from <snapshot>] [--to <snapshot>]',
     '  memorix codegraph impact --path <relative-source-path>',
@@ -116,25 +122,34 @@ function compactFacts(project: { rootPath: string }): { facts: string[]; dirty:
   return { facts, dirty: current.git.dirty };
 }
 
+function coerceAgentTarget(input?: string): AgentTarget | undefined {
+  const value = input?.trim().toLowerCase();
+  if (!value) return undefined;
+  if (WORKFLOW_AGENT_TARGETS.includes(value as AgentTarget)) return value as AgentTarget;
+  throw new Error('agent must be one of: ' + WORKFLOW_AGENT_TARGETS.join(', '));
+}
+
 export default defineCommand({
   meta: {
     name: 'codegraph',
     description: 'Inspect and refresh CodeGraph Memory for the current project',
   },
   args: {
-    action: { type: 'string', description: 'Action: status, refresh, diff, impact, or context-pack' },
+    action: { type: 'string', description: 'Action: status, refresh, diff, impact, init, sync, or context-pack' },
     task: { type: 'string', description: 'Task text for context-pack' },
     path: { type: 'string', description: 'Indexed relative source path for impact' },
     limit: { type: 'string', description: 'Max active memories to inspect for context-pack' },
     from: { type: 'string', description: 'Earlier CodeGraph snapshot id for diff' },
     to: { type: 'string', description: 'Later CodeGraph snapshot id for diff' },
     impactLimit: { type: 'string', description: 'Maximum graph relations to inspect for diff impact' },
+    agent: { type: 'string', description: 'Optional target agent for compatible workflow selection' },
     json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+    briefJson: { type: 'boolean', description: 'Emit only the bounded agent brief and receipt JSON for context-pack' },
   },
   run: async ({ args }) => {
     const positional = (args._ as string[]) ?? [];
     const action = (positional[0] || (args.action as string | undefined) || 'status').toLowerCase();
-    const asJson = !!args.json;
+    const asJson = !!args.json || !!args.briefJson;
 
     try {
       const { project, dataDir, reader } = await getCliProjectContext();
@@ -206,6 +221,27 @@ export default defineCommand({
           return;
         }
 
+        case 'init':
+        case 'sync': {
+          const lifecycle = await runExternalCodeGraphLifecycle({
+            action,
+            projectRoot: project.rootPath,
+            mode: codegraphConfig.externalContext,
+            command: codegraphConfig.externalCommand,
+            timeoutMs: codegraphConfig.externalTimeoutMs,
+          });
+          emitResult(
+            { project, lifecycle, providerQuality: lifecycle.quality },
+            [
+              lifecycle.message,
+              `- External semantic CodeGraph: ${lifecycle.health.state}`,
+              `- Task-scoped provider: ${lifecycle.quality.selected} (${lifecycle.quality.selectedQuality})`,
+            ].join('\n'),
+            asJson,
+          );
+          return;
+        }
+
         case 'diff': {
           const snapshots = store.listSnapshots(project.id, 2);
           const fromSnapshotId = (args.from as string | undefined)?.trim() || snapshots[1]?.id;
@@ -299,13 +335,20 @@ export default defineCommand({
               ? { runtimeCautions: [{ kind: 'external-codegraph-fallback' as const, message: external.caution }] }
               : {}),
             reader,
+            agent: coerceAgentTarget(args.agent as string | undefined),
           });
-          emitResult({ project, pack, providerQuality: external.quality }, buildContextPackPrompt(pack), asJson);
+          emitResult(
+            args.briefJson && pack.workset
+              ? buildBoundedContextReceipt({ workset: pack.workset, providerQuality: external.quality })
+              : { project, pack, providerQuality: external.quality },
+            buildContextPackPrompt(pack),
+            asJson,
+          );
           return;
         }
 
         default:
-          emitError(`unknown codegraph action "${action}". Use "status", "refresh", "diff", "impact", or "context-pack".`, asJson);
+          emitError(`unknown codegraph action "${action}". Use "status", "refresh", "init", "sync", "diff", "impact", or "context-pack".`, asJson);
       }
     } catch (error) {
       emitError(error instanceof Error ? error.message : String(error), asJson);

package/src/cli/commands/context.ts

@@ -7,6 +7,9 @@ import {
 } from '../../codegraph/auto-context.js';
 import { getAllObservations } from '../../memory/observations.js';
 import { filterReadableObservations } from '../../memory/visibility.js';
+import { buildBoundedContextReceipt } from '../../knowledge/context-receipt.js';
+import { WORKFLOW_AGENT_TARGETS } from '../../knowledge/workflows.js';
+import type { AgentTarget } from '../../types.js';
 import { emitError, emitResult, getCliProjectContext } from './operator-shared.js';
 
 function coerceRefreshMode(input?: string): AutoContextRefreshMode {
@@ -15,6 +18,13 @@ function coerceRefreshMode(input?: string): AutoContextRefreshMode {
   throw new Error('refresh must be one of: auto, always, never');
 }
 
+function coerceAgentTarget(input?: string): AgentTarget | undefined {
+  const value = input?.trim().toLowerCase();
+  if (!value) return undefined;
+  if (WORKFLOW_AGENT_TARGETS.includes(value as AgentTarget)) return value as AgentTarget;
+  throw new Error('agent must be one of: ' + WORKFLOW_AGENT_TARGETS.join(', '));
+}
+
 export default defineCommand({
   meta: {
     name: 'context',
@@ -29,10 +39,12 @@ export default defineCommand({
     },
     resume: { type: 'boolean', description: 'Always include the bounded prior-work projection' },
     refresh: { type: 'string', description: 'Project scan policy: auto, always, or never' },
+    agent: { type: 'string', description: 'Optional target agent for compatible workflow selection' },
     json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+    briefJson: { type: 'boolean', description: 'Emit only the bounded agent brief and receipt JSON' },
   },
   run: async ({ args }) => {
-    const asJson = !!args.json;
+    const asJson = !!args.json || !!args.briefJson;
     const task = (args.task as string | undefined)?.trim()
       || (args.input as string | undefined)?.trim()
       || undefined;
@@ -44,13 +56,13 @@ export default defineCommand({
         dataDir,
         observations: filterReadableObservations(getAllObservations(), reader),
         task,
+        agent: coerceAgentTarget(args.agent as string | undefined),
         refresh: coerceRefreshMode(args.refresh as string | undefined),
         reader,
         ...(args.resume ? { continuation: 'always' as const } : {}),
       });
 
-      emitResult(
-        {
+      const detailed = {
           project,
           lens: context.lens,
           brief: buildAutoProjectBrief(context),
@@ -61,7 +73,11 @@ export default defineCommand({
           workset: context.workset,
           ...(context.task ? { task: context.task } : {}),
           ...(context.continuation ? { continuation: context.continuation } : {}),
-        },
+      };
+      emitResult(
+        args.briefJson
+          ? buildBoundedContextReceipt({ workset: context.workset, providerQuality: context.providerQuality })
+          : detailed,
         formatAutoProjectContextPrompt(context),
         asJson,
       );