memorix 1.6.0 → 1.6.1

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.6.0",
+  "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.6.0",
+  "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.6.0",
+  "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.6.0",
+  "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.6.0",
+  "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.6.0",
+  "version": "1.6.1",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.6.0",
+  "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.6.0",
+  "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.6.0",
+  "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.6.0",
+  "version": "1.6.1",
   "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.6.0",
+      "version": "1.6.1",
       "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/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/doctor.ts

@@ -131,6 +131,7 @@ export default defineCommand({
     let bgRunning = false;
     let bgPort = 0;
     let bgPid = 0;
+    let backgroundHealthy = false;
 
     try {
       if (existsSync(bgStatePath)) {
@@ -148,7 +149,7 @@ export default defineCommand({
       // Health check
       try {
         const http = await import('node:http');
-        const healthy = await new Promise<boolean>((resolve) => {
+        backgroundHealthy = await new Promise<boolean>((resolve) => {
           const req = http.request({ hostname: '127.0.0.1', port: bgPort, path: '/api/team', timeout: 3000 }, (res) => {
             res.resume();
             resolve(res.statusCode === 200);
@@ -157,7 +158,7 @@ export default defineCommand({
           req.on('timeout', () => { req.destroy(); resolve(false); });
           req.end();
         });
-        if (healthy) {
+        if (backgroundHealthy) {
           lines.push(ok('Health check: OK'));
         } else {
           lines.push(warn('Health check: FAILED (process alive but not responding)'));
@@ -165,8 +166,9 @@ export default defineCommand({
         }
       } catch {
         lines.push(warn('Health check: could not connect'));
+        issues.push('Background process is alive but its health endpoint could not be reached. Try "memorix background restart".');
       }
-      report.mode = { type: 'background', pid: bgPid, port: bgPort, healthy: true };
+      report.mode = { type: 'background', pid: bgPid, port: bgPort, healthy: backgroundHealthy };
     } else {
       lines.push(info('Background control plane: not running'));
       lines.push(info('Current invocation: CLI (stdio)'));
@@ -210,20 +212,49 @@ export default defineCommand({
       } else {
         lines.push(ok(`Mode: ${mode}`));
 
-        // Try to initialize provider to check real status
-        const { getEmbeddingProvider } = await import('../../embedding/provider.js');
-        const provider = await getEmbeddingProvider();
+        // A running control plane is the source of truth for runtime health.
+        // A fresh doctor process must not overwrite a live 401/402/timeout
+        // diagnosis with a static "configured = ready" result.
+        let controlPlaneEmbedding: {
+          status?: string;
+          provider?: { name?: string; dimensions?: number };
+          failure?: { kind?: string; retryAfterMs?: number };
+        } | undefined;
+        if (bgRunning) {
+          try {
+            const response = await fetch(`http://127.0.0.1:${bgPort}/health`, { signal: AbortSignal.timeout(3_000) });
+            if (response.ok) {
+              const health = await response.json() as { embedding?: typeof controlPlaneEmbedding };
+              controlPlaneEmbedding = health.embedding;
+            }
+          } catch { /* health is advisory; fall back to a local probe */ }
+        }
 
-        if (provider) {
-          lines.push(ok(`Provider: ${provider.name} (${provider.dimensions}d)`));
-          lines.push(ok('Status: ready'));
-          lines.push(info('Search: hybrid (BM25 + vector)'));
-          report.embedding = { mode, status: 'ready', provider: provider.name, dimensions: provider.dimensions };
+        if (controlPlaneEmbedding?.status === 'degraded') {
+          const kind = controlPlaneEmbedding.failure?.kind ?? 'upstream';
+          const retryAfterMs = controlPlaneEmbedding.failure?.retryAfterMs;
+          const retry = typeof retryAfterMs === 'number' && retryAfterMs > 0
+            ? `; retry in ${Math.ceil(retryAfterMs / 1000)}s`
+            : '';
+          lines.push(warn(`Status: degraded in the running control plane (${kind}${retry})`));
+          lines.push(info('Search: degraded to BM25 fulltext until the provider recovers'));
+          issues.push('The running control plane has an unavailable embedding provider. Check provider credentials, billing, or connectivity.');
+          report.embedding = { mode, status: 'degraded', failure: kind };
         } else {
-          lines.push(warn('Status: temporarily unavailable'));
-          lines.push(info('Search: degraded to BM25 fulltext (no vector similarity)'));
-          issues.push(`Embedding mode is "${mode}" but provider failed to initialize. Check API keys/connectivity.`);
-          report.embedding = { mode, status: 'temporarily_unavailable' };
+          const { getEmbeddingProvider } = await import('../../embedding/provider.js');
+          const provider = await getEmbeddingProvider();
+
+          if (provider) {
+            lines.push(ok(`Provider: ${provider.name} (${provider.dimensions}d)`));
+            lines.push(ok('Status: ready'));
+            lines.push(info('Search: hybrid (BM25 + vector)'));
+            report.embedding = { mode, status: 'ready', provider: provider.name, dimensions: provider.dimensions };
+          } else {
+            lines.push(warn('Status: temporarily unavailable'));
+            lines.push(info('Search: degraded to BM25 fulltext (no vector similarity)'));
+            issues.push(`Embedding mode is "${mode}" but provider failed to initialize. Check API keys/connectivity.`);
+            report.embedding = { mode, status: 'temporarily_unavailable' };
+          }
         }
 
         // Check cached embeddings count