memorix 1.5.1 → 1.6.1

package/dist/vector-backfill-runner.js

@@ -3206,6 +3206,7 @@ __export(provider_exports, {
   MAX_INLINE_EMBEDDING_BYTES: () => MAX_INLINE_EMBEDDING_BYTES,
   UnsupportedEmbeddingModalityError: () => UnsupportedEmbeddingModalityError,
   getEmbeddingProvider: () => getEmbeddingProvider,
+  getEmbeddingRuntimeHealth: () => getEmbeddingRuntimeHealth,
   isEmbeddingExplicitlyDisabled: () => isEmbeddingExplicitlyDisabled,
   isVectorSearchAvailable: () => isVectorSearchAvailable,
   resetProvider: () => resetProvider,
@@ -3313,13 +3314,36 @@ function isTemporaryEmbeddingFailure(error) {
   if (!(error instanceof Error)) return false;
   return /embedding api error \(401\)/i.test(error.message) || /invalid_api_key/i.test(error.message) || /incorrect api key/i.test(error.message) || /unauthorized/i.test(error.message) || /embedding api timeout/i.test(error.message) || /embedding api error \((402|429|5\d\d)\)/i.test(error.message) || /quota exceeded/i.test(error.message) || /account balance/i.test(error.message) || /fetch failed/i.test(error.message) || /econnreset/i.test(error.message) || /econnrefused/i.test(error.message) || /temporarily unavailable/i.test(error.message);
 }
+function classifyEmbeddingFailure(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (/embedding api error \(401\)|invalid_api_key|incorrect api key|unauthorized/i.test(message)) {
+    return "authorization";
+  }
+  if (/embedding api error \(402\)|quota exceeded|account balance/i.test(message)) {
+    return "billing";
+  }
+  if (/embedding api timeout|abort/i.test(message)) {
+    return "timeout";
+  }
+  return "upstream";
+}
 function markTemporaryFailure(reason) {
   provider = null;
   initPromise = null;
   lastInitWasTemporaryFailure = true;
   lastFailureTimestamp = Date.now();
+  lastEmbeddingFailure = {
+    kind: classifyEmbeddingFailure(reason),
+    occurredAt: lastFailureTimestamp
+  };
   const message = reason instanceof Error ? reason.message : String(reason);
-  warnOnce(`[memorix] Embedding provider temporarily unavailable at runtime: ${message}`);
+  warnOnce(`[memorix] Embedding provider unavailable at runtime: ${message}`);
+}
+function markProviderReady(candidate) {
+  provider = wrapProvider(candidate);
+  lastInitWasTemporaryFailure = false;
+  lastEmbeddingFailure = null;
+  return provider;
 }
 async function createFastEmbedProvider() {
   try {
@@ -3435,35 +3459,35 @@ async function getEmbeddingProvider(options = {}) {
     if (mode === "fastembed") {
       const initialized = await createFastEmbedProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
     if (mode === "transformers") {
       const initialized = await createTransformersProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
     if (mode === "api") {
       const initialized = await createAPIProvider(options);
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
     if (hasAPIEmbeddingConfig()) {
       const initialized = await createAPIProvider(options);
       if (initialized) {
-        provider = wrapProvider(initialized);
+        provider = markProviderReady(initialized);
         warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
         return provider;
       }
     }
     const localFallback = await createLocalFallbackProvider();
     if (localFallback) {
-      provider = wrapProvider(localFallback);
+      provider = markProviderReady(localFallback);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -3485,6 +3509,27 @@ async function isVectorSearchAvailable() {
   const p = await getEmbeddingProvider();
   return p !== null;
 }
+function getEmbeddingRuntimeHealth() {
+  const mode = getEmbeddingMode2();
+  if (mode === "off") return { status: "disabled" };
+  if (lastInitWasTemporaryFailure && lastEmbeddingFailure) {
+    return {
+      status: "degraded",
+      failure: {
+        kind: lastEmbeddingFailure.kind,
+        occurredAt: new Date(lastEmbeddingFailure.occurredAt).toISOString(),
+        retryAfterMs: Math.max(0, RETRY_COOLDOWN_MS - (Date.now() - lastEmbeddingFailure.occurredAt))
+      }
+    };
+  }
+  if (provider) {
+    return {
+      status: "ready",
+      provider: { name: provider.name, dimensions: provider.dimensions }
+    };
+  }
+  return { status: "uninitialized" };
+}
 function isEmbeddingExplicitlyDisabled() {
   return getEmbeddingMode2() === "off";
 }
@@ -3493,10 +3538,11 @@ function resetProvider() {
   initPromise = null;
   lastInitWasTemporaryFailure = false;
   lastFailureTimestamp = 0;
+  lastEmbeddingFailure = null;
   lastEmbeddingWarning = "";
   lastEmbeddingWarningAt = 0;
 }
-var EmbeddingInputError, UnsupportedEmbeddingModalityError, MAX_INLINE_EMBEDDING_BYTES, provider, initPromise, lastInitWasTemporaryFailure, lastEmbeddingWarning, lastEmbeddingWarningAt, WARNING_COOLDOWN_MS, RETRY_COOLDOWN_MS, lastFailureTimestamp;
+var EmbeddingInputError, UnsupportedEmbeddingModalityError, MAX_INLINE_EMBEDDING_BYTES, provider, initPromise, lastInitWasTemporaryFailure, lastEmbeddingFailure, lastEmbeddingWarning, lastEmbeddingWarningAt, WARNING_COOLDOWN_MS, RETRY_COOLDOWN_MS, lastFailureTimestamp;
 var init_provider = __esm({
   "src/embedding/provider.ts"() {
     "use strict";
@@ -3521,6 +3567,7 @@ var init_provider = __esm({
     provider = null;
     initPromise = null;
     lastInitWasTemporaryFailure = false;
+    lastEmbeddingFailure = null;
     lastEmbeddingWarning = "";
     lastEmbeddingWarningAt = 0;
     WARNING_COOLDOWN_MS = 3e4;
@@ -147780,6 +147827,7 @@ var init_task_lens = __esm({
 var workflows_exports = {};
 __export(workflows_exports, {
   WORKFLOW_ADAPTER_TARGETS: () => WORKFLOW_ADAPTER_TARGETS,
+  WORKFLOW_AGENT_TARGETS: () => WORKFLOW_AGENT_TARGETS,
   applyWorkflowAdapter: () => applyWorkflowAdapter,
   importWindsurfWorkflows: () => importWindsurfWorkflows,
   parseWorkflowMarkdown: () => parseWorkflowMarkdown,
@@ -147845,7 +147893,7 @@ function optionalStatus(data) {
   return value;
 }
 function normalizeAgents(values) {
-  const unknown3 = values.filter((value) => !KNOWN_AGENTS.includes(value));
+  const unknown3 = values.filter((value) => !WORKFLOW_AGENT_TARGETS.includes(value));
   if (unknown3.length > 0) {
     throw new Error("workflow frontmatter has unsupported agent: " + unknown3[0]);
   }
@@ -148121,7 +148169,7 @@ function taskScore(workflow, task) {
   return { score, reasons: [...new Set(reasons)] };
 }
 function selectWorkflows(input) {
-  const selected = input.workflows.filter((workflow) => workflow.status === "active").map((workflow) => {
+  const selected = input.workflows.filter((workflow) => workflow.status === "active" && (!input.agent || workflow.compatibleAgents.includes(input.agent))).map((workflow) => {
     const match2 = taskScore(workflow, input.task);
     const cautions = input.store && input.projectId ? input.store.recentFailureCautions(input.projectId, workflow.id) : [];
     return {
@@ -148401,7 +148449,7 @@ async function selectWorkspaceWorkflows(input) {
     errors: synced.errors
   };
 }
-var KNOWN_AGENTS, WORKFLOW_ADAPTER_TARGETS, STATUS_VALUES, LENS_TERMS, GENERIC_WORKFLOW_LENSES, GENERIC_WORKFLOW_TERMS;
+var WORKFLOW_AGENT_TARGETS, WORKFLOW_ADAPTER_TARGETS, STATUS_VALUES, LENS_TERMS, GENERIC_WORKFLOW_LENSES, GENERIC_WORKFLOW_TERMS;
 var init_workflows2 = __esm({
   "src/knowledge/workflows.ts"() {
     "use strict";
@@ -148413,7 +148461,7 @@ var init_workflows2 = __esm({
     init_workflow_store();
     init_outcome_store();
     init_task_lens();
-    KNOWN_AGENTS = [
+    WORKFLOW_AGENT_TARGETS = [
       "windsurf",
       "cursor",
       "claude-code",

package/docs/1.2.4-PERSISTENT-MEMORY-DELIVERY.md

@@ -26,7 +26,7 @@ database, a transcript archive, or another default MCP tool.
 | Start a new, unrelated task | A bounded task Workset. No automatic prior-session text. |
 | Continue or take over prior work | The same Workset plus a bounded prior-work projection. |
 | MCP is available | Use the existing `memorix_project_context` tool with the real task. |
-| MCP is unavailable | Make one CLI call: `memorix resume "<task>" --json` for continuation or `memorix context "<task>" --json` for a new task. |
+| MCP is unavailable | Make one CLI call: `memorix resume "<task>" --brief-json` for continuation or `memorix context "<task>" --brief-json` for a new task. `--json` remains the detailed diagnostic form. |
 | Claude Code hook is installed | An explicit continuation prompt receives the same bounded prior-work Workset through the official `UserPromptSubmit` context channel, unless `memory.inject = "silent"`. |
 | Read-only assessment | The brief may be read, but Memorix does not persist a new observation unless the user explicitly asks to save one. |
 | Need a deliberate session handoff | Keep using the explicit session/handoff surfaces; this projection does not replace them. |

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -58,7 +58,7 @@ An unbound terminal is intentionally project-scoped: it reads and writes project
 
 Long-term memory is a reviewed layer, not a generic global note store. `memorix memory long-term add` creates a candidate; `qualify` and `approve` are explicit audit transitions before it can appear in a bounded task Workset. A project-derived observation, code fact, Git fact, test, session, Claim, or workflow stays project-bound. Only manual or user-confirmed `user + portable` records can cross local projects for the same local installation identity. When one is task-matched in a Workset, it is intentionally usable background even if its origin differs; use its `durable:<id>` reference with `memorix_detail` only when the full record is needed. Use `archive` or `supersede` when a durable item is no longer current.
 
-`--cwd <git-project>` is the canonical way to run direct CLI work from outside a repository. It changes the command's project anchor only; Git remains the source of truth for final project identity.
+`--cwd <git-project>` is the canonical way to run direct CLI work from outside a repository. It changes the command's project anchor only; Git remains the source of truth for final project identity. Existing directories are canonicalized to their real filesystem paths before binding, which prevents macOS aliases such as `/var` and `/private/var` from splitting one project or hiding a Claude local MCP entry.
 
 Use MCP when:
 
@@ -164,7 +164,12 @@ Do not assume the HTTP connection alone tells Memorix which project the user mea
 
 The HTTP service is normally started with `memorix background start`; the same project-binding rules apply when you run `memorix serve-http --port 3211` in the foreground.
 
-HTTP MCP sessions idle out after 30 minutes by default. If the user's HTTP MCP client is sensitive to stale session IDs after long idle periods, set `MEMORIX_SESSION_TIMEOUT_MS` before starting or restarting the service. Example: `MEMORIX_SESSION_TIMEOUT_MS=86400000` keeps sessions alive for 24 hours.
+HTTP MCP sessions idle out after 12 hours by default. An expired session now
+receives a fast `404` reinitialize hint instead of a generic transport failure.
+If the user's HTTP MCP client needs a longer idle period, set
+`MEMORIX_SESSION_TIMEOUT_MS` before starting or restarting the service.
+Example: `MEMORIX_SESSION_TIMEOUT_MS=86400000` keeps sessions alive for 24
+hours. Set it to `0` only when the host has its own reliable session cleanup.
 
 ### Do not confuse project config and global config
 
@@ -702,7 +707,10 @@ If it shows "Not running" or "dead":
 memorix background ensure
 ```
 
-If the client is connected but starts failing after roughly 30 minutes of no Memorix tool use, check for stale HTTP session expiry rather than treating it as project binding failure. Restart the service with a longer idle timeout:
+If the client is connected but starts failing after a long inactive period,
+check for the explicit stale-session `404` reinitialize hint rather than
+treating it as a project-binding failure. The default idle window is 12 hours;
+restart with a longer window only when the client genuinely needs it:
 
 ```powershell
 $env:MEMORIX_SESSION_TIMEOUT_MS = "86400000"

package/docs/API_REFERENCE.md

@@ -115,7 +115,7 @@ MCP:
 - `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_graph_context` is an advanced compact graph overview. It starts from a small task-matched baseline and can add only directly related, evidence-governed memories. Its `Graph evidence` section includes relation provenance rather than recursively dumping graph neighbors.
 
-`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 an old `ACTIVE_WORK.md`, legacy `progress.txt`, or legacy dev-log note as historical when it predates 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.
+`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 an old `ACTIVE_WORK.md`, legacy `progress.txt`, or legacy dev-log note as historical when it predates the latest changelog, so agents should treat current facts as the source of truth when files disagree. Use `--brief-json` for the same bounded brief plus a receipt of selected and omitted evidence; `--json` remains the detailed legacy diagnostic form. 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.
 
@@ -652,7 +652,7 @@ Coordination state is opt-in project state for tasks, handoff messages, locks, a
 
 Runtime environment:
 
-- `MEMORIX_SESSION_TIMEOUT_MS` — HTTP MCP session idle timeout in milliseconds. Default: `1800000` (30 minutes). Increase this for clients that do not transparently reinitialize after stale HTTP session IDs, for example `86400000` for 24 hours.
+- `MEMORIX_SESSION_TIMEOUT_MS` — HTTP MCP session idle timeout in milliseconds. Default: `43200000` (12 hours). Expired session IDs receive a fast `404` with a reinitialize hint. Increase this for long-lived clients, for example `86400000` for 24 hours; set `0` only when the host provides reliable lifecycle cleanup.
 
 ### `team_manage`
 

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/docs/DOCKER.md

@@ -128,7 +128,11 @@ docker compose ps
 
 ### HTTP session idle timeout
 
-The HTTP MCP transport defaults to a 30-minute idle timeout. The example `compose.yaml` raises this to 24 hours for IDEs that keep one HTTP MCP session open while the user reads diffs, runs tests, or switches focus.
+The HTTP MCP transport defaults to a 12-hour idle timeout. The example
+`compose.yaml` raises this to 24 hours for IDEs that keep one HTTP MCP session
+open while the user reads diffs, runs tests, or switches focus. When a session
+does expire, the service returns a fast `404` so the client can initialize a
+fresh MCP session.
 
 To change it:
 

package/docs/PERFORMANCE.md

@@ -71,7 +71,7 @@ On the release development machine used for this check, the healthy HTTP service
 
 | Knob | Default | Use When |
 | --- | --- | --- |
-| `MEMORIX_SESSION_TIMEOUT_MS` | `1800000` (30 min) | Increase for HTTP MCP clients that do not recover from stale session IDs after idle time |
+| `MEMORIX_SESSION_TIMEOUT_MS` | `43200000` (12 h) | Set a shorter GC window for supervised clients, or `0` to disable idle session GC |
 | `MEMORIX_FORMATION_TIMEOUT_MS` | `12000` (12 s) | Raise when LLM-backed formation should outlive slow proxy/provider hops |
 | `MEMORIX_LLM_API_KEY` / `OPENAI_API_KEY` | unset | Enable LLM-backed enrichment, extraction, rerank, or skill generation |
 | `MEMORIX_LLM_TIMEOUT_MS` | `30000` (30 s) | Bound a single LLM-backed extraction/resolve call |
@@ -86,7 +86,7 @@ On the release development machine used for this check, the healthy HTTP service
 ## Operator Guidance
 
 - For memory-only use, prefer stdio MCP or a lightweight `memorix_session_start`; do not join orchestration coordination state by default.
-- For long-lived IDE sessions over HTTP, set `MEMORIX_SESSION_TIMEOUT_MS=86400000` before `memorix background start` if your client is stale-session-sensitive.
+- HTTP sessions now default to 12 hours and return a fast `404` with a reinitialize hint after expiry. Set `MEMORIX_SESSION_TIMEOUT_MS=0` only when the host has its own reliable lifecycle cleanup; otherwise retain a bounded GC window.
 - If LLM-backed formation is timing out against a slow proxy/provider, raise `MEMORIX_FORMATION_TIMEOUT_MS` and keep it higher than `MEMORIX_LLM_TIMEOUT_MS`, because the full pipeline can include multiple LLM-backed stages.
 - For Docker, use it when you want a managed HTTP service. Do not use image size alone as the runtime memory estimate.
 - For orchestrated subagent work, expect CPU and disk activity proportional to the spawned agents and verification commands.

package/docs/README.md

@@ -117,11 +117,13 @@ Historical/deep-reference documents may describe older designs. If they conflict
 
 ## Current Product Line
 
-The released product is on the **1.4 line**. The current baseline has:
+The released product is on the **1.6 line**. The current baseline has:
 
 - `memorix setup --agent <agent> --global` is the default agent integration command
 - `memorix serve` is the manual stdio MCP server for external agents
 - `memorix background start` runs the shared HTTP MCP service and dashboard
+- context and CodeGraph commands return bounded task receipts before detailed diagnostics
+- HTTP MCP sessions have a bounded, explicit lifecycle and fail with a reinitialize hint after expiry
 - `memorix integrate --agent <agent>` and `memorix hooks install --agent <agent>` remain manual/fallback generation commands
 - `memorix` / `memcode` open memcode, the bundled terminal agent that uses the same Memorix memory pool
 - `~/.memorix/config.toml` and project `memorix.toml` are the user-facing configuration model

package/docs/SETUP.md

@@ -42,7 +42,7 @@ Memorix project identity comes from Git. Open or initialize a real Git repositor
 git init
 ```
 
-`projectRoot` and current working directory are detection anchors. The final project identity is derived from the real Git root and remote metadata.
+`projectRoot` and current working directory are detection anchors. The final project identity is derived from the real Git root and remote metadata. Memorix resolves an existing project directory to its real filesystem path before binding it, so equivalent macOS paths such as `/var/...` and `/private/var/...` do not create separate project or Claude local-MCP entries.
 
 ---
 
@@ -247,13 +247,19 @@ Generic HTTP MCP config:
 
 For multi-project HTTP usage, agents should call `memorix_session_start(projectRoot=...)` with the absolute workspace path when available. This prevents cross-project drift when the background service is shared.
 
-HTTP sessions idle out after 30 minutes by default. For clients that do not recover gracefully from stale HTTP session IDs:
+HTTP sessions idle out after 12 hours by default. An expired session receives a
+fast `404` that tells the client to initialize again, rather than being treated
+as a project-binding failure. For clients that intentionally need a longer
+window:
 
 ```powershell
 $env:MEMORIX_SESSION_TIMEOUT_MS = "86400000"
 memorix background restart
 ```
 
+Set `MEMORIX_SESSION_TIMEOUT_MS=0` only when the host has its own reliable
+session cleanup; otherwise keep a bounded idle window.
+
 ### Option E: Docker HTTP service
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "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.1",
   "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.1",
   "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.1",
   "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.1",
   "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.1",
   "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.1",
   "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.1",
   "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.1",
   "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.1",
   "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.5.1",
+      "version": "1.6.1",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/commands/agent-integrations.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
@@ -580,11 +580,17 @@ function sanitizeServer(server: MCPServerEntry): AgentMcpCheck['server'] {
 }
 
 function normalizeProjectKey(projectRoot: string): string {
-  return resolve(projectRoot).replace(/\\/g, '/').toLowerCase();
+  return canonicalProjectPath(projectRoot).toLowerCase();
 }
 
 function defaultClaudeProjectKey(projectRoot: string): string {
-  return resolve(projectRoot).replace(/\\/g, '/');
+  return canonicalProjectPath(projectRoot);
+}
+
+function canonicalProjectPath(projectRoot: string): string {
+  const resolved = resolve(projectRoot);
+  const canonical = existsSync(resolved) ? realpathSync(resolved) : resolved;
+  return canonical.replace(/\\/g, '/');
 }
 
 function getClaudeLocalConfigPath(): string {

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);