memorix 1.9.4 → 1.9.5

package/src/cli/commands/setup.ts

@@ -33,6 +33,7 @@ import { TraeMCPAdapter } from '../../workspace/mcp-adapters/trae.js';
 import { DshMCPAdapter } from '../../workspace/mcp-adapters/dsh.js';
 import { WorkbuddyMCPAdapter } from '../../workspace/mcp-adapters/workbuddy.js';
 import { CodeBuddyMCPAdapter } from '../../workspace/mcp-adapters/codebuddy.js';
+import { GrokMCPAdapter } from '../../workspace/mcp-adapters/grok.js';
 import { getSetupIntegrationRows as readSetupIntegrationRows } from '../../integrations/registry.js';
 import { OFFICIAL_MEMORIX_SKILLS } from '../../hooks/official-skills.js';
 import { getCliVersion } from '../version.js';
@@ -212,9 +213,11 @@ export function buildSetupPlan(options: {
   plugin?: boolean;
   global?: boolean;
 }): SetupPlan {
-  // Grok owns its MCP configuration through `grok mcp`; Memorix setup only
-  // installs the independent hooks/rules integration for this target.
-  const mcp = options.agent === 'grok' ? 'none' : options.mcp ?? 'stdio';
+  // Grok MCP stays host-owned by default (`grok mcp`). An explicit
+  // `--mcp http` is the exception: write the shared control-plane URL.
+  const mcp = options.agent === 'grok'
+    ? (options.mcp === 'http' ? 'http' : 'none')
+    : options.mcp ?? 'stdio';
   const actions: SetupAction[] = [];
   const isPackageOwnedAgent = options.agent !== 'all' && PACKAGE_OWNED_INTEGRATION_AGENTS.has(options.agent);
   const includeHooks = options.hooks ?? true;
@@ -391,7 +394,7 @@ function relativePosix(from: string, to: string): string {
   return rel;
 }
 
-export type McpConfigAgent = Exclude<AgentName, 'pi' | 'grok'>;
+export type McpConfigAgent = Exclude<AgentName, 'pi'>;
 
 export function getMcpAdapter(agent: McpConfigAgent): MCPConfigAdapter {
   const adapters: Record<McpConfigAgent, MCPConfigAdapter> = {
@@ -411,17 +414,20 @@ export function getMcpAdapter(agent: McpConfigAgent): MCPConfigAdapter {
     trae: new TraeMCPAdapter(),
     dsh: new DshMCPAdapter(),
     workbuddy: new WorkbuddyMCPAdapter(),
+    grok: new GrokMCPAdapter(),
   };
   return adapters[agent];
 }
 
+export const MEMORIX_HTTP_MCP_URL = 'http://localhost:3211/mcp';
+
 export function buildMemorixServer(mcp: Exclude<SetupMcpTransport, 'none'>): MCPServerEntry {
   if (mcp === 'http') {
     return {
       name: 'memorix',
       command: '',
       args: [],
-      url: 'http://localhost:3211/mcp',
+      url: MEMORIX_HTTP_MCP_URL,
     };
   }
 
@@ -434,6 +440,45 @@ export function buildMemorixServer(mcp: Exclude<SetupMcpTransport, 'none'>): MCP
   };
 }
 
+function toHttpMemorixServer(existing: Record<string, unknown>): Record<string, unknown> {
+  const next: Record<string, unknown> = { url: MEMORIX_HTTP_MCP_URL };
+  if (existing.alwaysLoad === true) next.alwaysLoad = true;
+  if (typeof existing.type === 'string') next.type = 'http';
+  return next;
+}
+
+/**
+ * Rewrite a copied plugin/extension MCP manifest from stdio `memorix serve`
+ * to the shared HTTP control plane. Leaves unrelated keys intact.
+ */
+export async function rewriteBundledMemorixMcpToHttp(root: string): Promise<string[]> {
+  const candidates = ['.mcp.json', 'mcp_config.json', 'gemini-extension.json']
+    .map((name) => path.join(root, name));
+  const rewritten: string[] = [];
+
+  for (const filePath of candidates) {
+    if (!existsSync(filePath)) continue;
+    let doc: unknown;
+    try {
+      doc = JSON.parse(await readFile(filePath, 'utf-8'));
+    } catch {
+      continue;
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) continue;
+    const record = doc as Record<string, unknown>;
+    const servers = record.mcpServers;
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers)) continue;
+    const serverMap = servers as Record<string, unknown>;
+    const existing = serverMap.memorix;
+    if (!existing || typeof existing !== 'object' || Array.isArray(existing)) continue;
+    serverMap.memorix = toHttpMemorixServer(existing as Record<string, unknown>);
+    await writeFile(filePath, JSON.stringify(record, null, 2) + '\n', 'utf-8');
+    rewritten.push(filePath);
+  }
+
+  return rewritten;
+}
+
 function mergeJsonMcpConfig(existingContent: string | null, generatedContent: string): string {
   let generated: Record<string, unknown>;
   try {
@@ -781,7 +826,7 @@ export async function installMcpConfig(options: {
   }
 
   const generated = adapter.generate([server]);
-  const content = options.agent === 'codex'
+  const content = options.agent === 'codex' || options.agent === 'grok'
     ? mergeTomlMcpConfig(existingContent, generated)
     : options.agent === 'hermes'
       ? mergeYamlMcpConfig(existingContent, generated)
@@ -1456,7 +1501,12 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
   const hasCodeBuddyPlugin = plan.actions.includes('codebuddy-plugin') && agent === 'codebuddy';
   // Codex's supported default is the user-level plugin. Never create a
   // project-local .codex/config.toml as an implicit fallback.
-  const wantsMcpConfig = plan.mcp !== 'none' && agent !== 'pi' && agent !== 'grok' && !(agent === 'codex' && !global);
+  // Grok MCP stays host-owned unless the caller passed --mcp http.
+  const wantsMcpConfig = plan.mcp !== 'none'
+    && agent !== 'pi'
+    && !(agent === 'codex' && !global)
+    && !(agent === 'grok' && plan.mcp !== 'http');
+  const bundledMcpRoots: string[] = [];
 
   if (PLUGIN_PACKAGE_AGENTS.has(agent) && plan.includePlugin && !global) {
     p.log.info(`${agent}: project setup leaves user-level plugins untouched. Run \`memorix setup --agent ${agent} --global\` to install its plugin, skills, and lifecycle hooks.`);
@@ -1467,6 +1517,7 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
       agent: agent as PluginInstallOptions['agent'],
       includeHooks: plan.includeHooks,
     });
+    bundledMcpRoots.push(result.pluginPath);
     p.log.success(`${agent}: plugin package -> ${result.pluginPath}`);
     if (result.marketplacePath) {
       p.log.info(`${agent}: marketplace -> ${result.marketplacePath}`);
@@ -1498,6 +1549,7 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
 
   if (hasCodeBuddyPlugin) {
     const result = await installCodeBuddyPluginPackage({ includeHooks: plan.includeHooks });
+    bundledMcpRoots.push(result.pluginPath);
     p.log.success(`${agent}: plugin -> ${result.pluginPath}`);
     p.log.info(`${agent}: marketplace -> ${result.marketplacePath}`);
     const install = tryInstallCodeBuddyPlugin(result.marketplaceRoot);
@@ -1509,6 +1561,7 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
 
   if (hasExtensionPackage) {
     const result = await installGeminiExtensionPackage();
+    bundledMcpRoots.push(result.extensionPath);
     p.log.success(`${agent}: extension package -> ${result.extensionPath}`);
     p.log.info(result.installHint);
   }
@@ -1524,6 +1577,7 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
 
   if (hasOpenClawBundle) {
     const result = await installOpenClawBundlePackage({ includeHooks: plan.includeHooks });
+    bundledMcpRoots.push(result.bundlePath);
     p.log.success(`${agent}: compatible bundle -> ${result.bundlePath}`);
     if (plan.includeHooks) {
       const install = tryInstallOpenClawBundle(result.bundlePath);
@@ -1537,6 +1591,7 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
 
   if (hasAntigravityPlugin) {
     const result = await installAntigravityPluginPackage({ global, projectRoot: targetRoot, includeHooks: plan.includeHooks });
+    bundledMcpRoots.push(result.pluginPath);
     p.log.success(`${agent}: plugin -> ${result.pluginPath}`);
     if (!plan.includeHooks) {
       p.log.info(`${agent}: hooks.json skipped because --noHooks was selected`);
@@ -1570,7 +1625,8 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
   }
 
   if (wantsMcpConfig) {
-    if ((hasPluginPackage || hasCodeBuddyPlugin || hasExtensionPackage || hasOpenClawBundle || hasAntigravityPlugin) && plan.mcp === 'stdio') {
+    const mcpOwnedByPackage = hasPluginPackage || hasCodeBuddyPlugin || hasExtensionPackage || hasOpenClawBundle || hasAntigravityPlugin;
+    if (mcpOwnedByPackage && plan.mcp === 'stdio') {
       const packageLabel = hasExtensionPackage
         ? 'extension package'
         : hasCodeBuddyPlugin
@@ -1581,6 +1637,13 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
             ? 'Antigravity plugin'
           : 'plugin package';
       p.log.info(`${agent}: stdio MCP is bundled in the ${packageLabel}`);
+    } else if (mcpOwnedByPackage && plan.mcp === 'http') {
+      for (const root of bundledMcpRoots) {
+        const rewritten = await rewriteBundledMemorixMcpToHttp(root);
+        for (const filePath of rewritten) {
+          p.log.success(`${agent}: plugin MCP -> HTTP ${filePath}`);
+        }
+      }
     } else {
       const mcp = plan.mcp === 'http' ? 'http' : 'stdio';
       const result = await installMcpConfig({ agent: agent as McpConfigAgent, projectRoot: targetRoot, global, mcp });
@@ -1637,7 +1700,11 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
   if (agent === 'pi') {
     p.log.info('pi: Pi has no MCP config lane in the current CLI; use the installed package extension and skill.');
   } else if (agent === 'grok') {
-    p.log.info('grok: lifecycle hooks write ~/.grok/hooks/memorix.json. MCP stays host-owned (do not write config.toml).');
+    if (plan.mcp === 'http') {
+      p.log.info('grok: wrote [mcp_servers.memorix] HTTP URL in Grok config.toml. Start the control plane with `memorix background start`.');
+    } else {
+      p.log.info('grok: lifecycle hooks write ~/.grok/hooks/memorix.json. MCP stays host-owned unless you pass `--mcp http`.');
+    }
     if (!global) p.log.info('grok: project hooks require `/hooks-trust` or launching Grok with `--trust`.');
   } else if (plan.mcp === 'stdio') {
     p.log.info(`${agent}: MCP server command is \`memorix serve\``);
@@ -1744,7 +1811,7 @@ export default defineCommand({
           { value: 'codex', label: 'Codex', hint: 'plugin package + marketplace + MCP' },
           { value: 'copilot', label: 'GitHub Copilot CLI', hint: 'plugin package + hooks + MCP' },
           { value: 'cursor', label: 'Cursor', hint: 'MCP + rules + skills' },
-          { value: 'grok', label: 'Grok Build', hint: 'hooks file; MCP stays host-owned' },
+          { value: 'grok', label: 'Grok Build', hint: 'hooks file; MCP host-owned unless --mcp http' },
           { value: 'gemini-cli', label: 'Gemini CLI', hint: 'extension + MCP' },
           { value: 'openclaw', label: 'OpenClaw', hint: 'bundle + hook pack + skills + MCP' },
           { value: 'hermes', label: 'Hermes Agent', hint: 'plugin + hooks + commands + skills + MCP' },

package/src/cli/commands/sync-store.ts

@@ -10,14 +10,40 @@ import { defineCommand } from 'citty';
 
 import { getCliProjectContext, emitError, emitResult } from './operator-shared.js';
 import { getObservationStore, initObservationStore } from '../../store/obs-store.js';
+import { getProjectDataDir } from '../../store/persistence.js';
 import { runSync } from '../../sync/engine.js';
 import { createSqliteSyncStore } from '../../sync/store-port.js';
 import { resolveSyncConfig, createRemote } from '../../sync/remote-factory.js';
+import { USER_SYNC_SCOPE_ID } from '../../sync/namespace.js';
+import type { SyncScope } from '../../sync/policy.js';
 import type { SyncReport } from '../../sync/types.js';
 
+function parseScope(raw: unknown): SyncScope {
+  const value = String(raw || 'project').toLowerCase();
+  if (value === 'project' || value === 'user') return value;
+  throw new Error('--scope must be one of: project, user');
+}
+
+async function openSyncStore(scope: SyncScope) {
+  if (scope === 'user') {
+    const dataDir = await getProjectDataDir(USER_SYNC_SCOPE_ID);
+    await initObservationStore(dataDir);
+    return {
+      projectId: USER_SYNC_SCOPE_ID,
+      syncStore: createSqliteSyncStore(dataDir, getObservationStore(), USER_SYNC_SCOPE_ID, { scope: 'user' }),
+    };
+  }
+  const { project, dataDir } = await getCliProjectContext();
+  await initObservationStore(dataDir);
+  return {
+    projectId: project.id,
+    syncStore: createSqliteSyncStore(dataDir, getObservationStore(), project.id),
+  };
+}
+
 function renderReport(report: SyncReport): string {
   const lines = [
-    `Store sync (${report.remote}) — device ${report.deviceId}${report.dryRun ? ' [dry-run]' : ''}`,
+    `Store sync (${report.remote}, scope ${report.scope}) — device ${report.deviceId}${report.dryRun ? ' [dry-run]' : ''}`,
     `- Pushed changes:   ${report.pushed}`,
     `- Pulled batches:   ${report.pulledBatches}`,
     `- Applied upserts:  ${report.applied}`,
@@ -48,22 +74,34 @@ export default defineCommand({
     'pull-only': { type: 'boolean', description: 'Only pull remote changes', default: false },
     through: { type: 'string', description: 'Compaction cutoff: device=sequence,device=sequence' },
     yes: { type: 'boolean', description: 'Confirm destructive remote compaction', default: false },
+    scope: {
+      type: 'string',
+      description: 'project (default: current Git project) or user (all local projects)',
+      default: 'project',
+    },
   },
   run: async ({ args }) => {
     const asJson = Boolean(args.json);
     const action = (args._ as string[])?.[0] || 'status';
+    let scope: SyncScope;
+    try {
+      scope = parseScope(args.scope);
+    } catch (err) {
+      emitError((err as Error).message, asJson);
+      process.exitCode = 2;
+      return;
+    }
     if (action === 'device') {
-      const { project, dataDir } = await getCliProjectContext();
-      await initObservationStore(dataDir);
-      const syncStore = createSqliteSyncStore(dataDir, getObservationStore(), project.id);
       const subaction = (args._ as string[])?.[1] || '';
       if (subaction !== 'rotate') {
         emitError('expected "memorix sync store device rotate"', asJson);
         process.exitCode = 2;
         return;
       }
+      // Device identity is per data directory, not per Git project.
+      const { projectId, syncStore } = await openSyncStore('user');
       const deviceId = syncStore.rotateDevice();
-      emitResult({ project: project.id, deviceId, rotated: true }, `Sync device identity rotated: ${deviceId}`, asJson);
+      emitResult({ project: projectId, scope: 'user', deviceId, rotated: true }, `Sync device identity rotated: ${deviceId}`, asJson);
       return;
     }
     if (action !== 'push' && action !== 'pull' && action !== 'status' && action !== 'compact') {
@@ -90,10 +128,7 @@ export default defineCommand({
       return;
     }
 
-    const { project, dataDir } = await getCliProjectContext();
-    await initObservationStore(dataDir);
-    const obsStore = getObservationStore();
-    const syncStore = createSqliteSyncStore(dataDir, obsStore, project.id);
+    const { projectId, syncStore } = await openSyncStore(scope);
 
     if (action === 'compact') {
       if (!args.yes && !args.dry) {
@@ -129,7 +164,7 @@ export default defineCommand({
       try {
         await remote.init({ create: false });
         const result = await remote.compact(through, { dryRun: Boolean(args.dry) });
-        emitResult({ project: project.id, through, ...result, dryRun: Boolean(args.dry) }, `Compaction candidates: ${result.candidates}; deleted: ${result.deleted}`, asJson);
+        emitResult({ project: projectId, scope, through, ...result, dryRun: Boolean(args.dry) }, `Compaction candidates: ${result.candidates}; deleted: ${result.deleted}`, asJson);
       } catch (err) {
         emitError((err as Error).message, asJson);
         process.exitCode = 1;
@@ -155,7 +190,7 @@ export default defineCommand({
           push: true,
           pull: true,
         });
-        emitResult({ project: project.id, ...report }, renderReport(report), asJson);
+        emitResult({ project: projectId, ...report }, renderReport(report), asJson);
       } catch (err) {
         emitError((err as Error).message, asJson);
         process.exitCode = 1;
@@ -182,7 +217,7 @@ export default defineCommand({
         push: doPush,
         pull: doPull,
       });
-      emitResult({ project: project.id, ...report }, renderReport(report), asJson);
+      emitResult({ project: projectId, ...report }, renderReport(report), asJson);
     } catch (err) {
       emitError((err as Error).message, asJson);
       process.exitCode = 1;

package/src/cli/commands/sync.ts

@@ -48,6 +48,32 @@ export default defineCommand({
       description: 'Emit machine-readable JSON output',
       default: false,
     },
+    scope: {
+      type: 'string',
+      description: 'Store sync scope: project (default) or user',
+      required: false,
+      default: 'project',
+    },
+    'push-only': {
+      type: 'boolean',
+      description: 'Store sync: only push local changes',
+      required: false,
+    },
+    'pull-only': {
+      type: 'boolean',
+      description: 'Store sync: only pull remote changes',
+      required: false,
+    },
+    through: {
+      type: 'string',
+      description: 'Store sync compaction cutoff: device=sequence[,device=sequence]',
+      required: false,
+    },
+    yes: {
+      type: 'boolean',
+      description: 'Store sync: confirm destructive remote compaction',
+      required: false,
+    },
   },
   run: async ({ args }) => {
     const section = (args._ as string[])?.[0] || '';

package/src/dashboard/server.ts

@@ -16,7 +16,7 @@ import { exec } from 'node:child_process';
 import { getBaseDataDir } from '../store/persistence.js';
 import { getObservationStore, initObservationStore } from '../store/obs-store.js';
 import { getSessionStore, initSessionStore } from '../store/session-store.js';
-import { initGraphStore, getGraphStore } from '../store/graph-store.js';
+import { initGraphStore } from '../store/graph-store.js';
 import type { TeamStore } from '../team/team-store.js';
 import { loadDotenv } from '../config/dotenv-loader.js';
 import { resetDotenv } from '../config/dotenv-loader.js';
@@ -309,8 +309,7 @@ async function handleApi(
             }
 
             case '/graph': {
-                await initGraphStore(effectiveDataDir);
-                const gStore = getGraphStore();
+                const gStore = await initGraphStore(effectiveDataDir, effectiveProjectId);
                 const graph = { entities: gStore.loadEntities(), relations: gStore.loadRelations() };
                 const graphObs = filterDashboardObservations(
                     await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }),
@@ -360,8 +359,8 @@ async function handleApi(
             }
 
             case '/stats': {
-                await initGraphStore(effectiveDataDir);
-                const graph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
+                const gStore = await initGraphStore(effectiveDataDir, effectiveProjectId);
+                const graph = { entities: gStore.loadEntities(), relations: gStore.loadRelations() };
                 const observations = filterDashboardObservations(
                     await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }),
                     effectiveProjectId,
@@ -584,10 +583,10 @@ async function handleApi(
             case '/knowledge-graph': {
                 const { generateKnowledgeGraph } = await import('../wiki/knowledge-graph.js');
                 const { initMiniSkillStore, getMiniSkillStore } = await import('../store/mini-skill-store.js');
-                const { initGraphStore, getGraphStore } = await import('../store/graph-store.js');
+                const { initGraphStore } = await import('../store/graph-store.js');
 
                 await initMiniSkillStore(effectiveDataDir);
-                await initGraphStore(effectiveDataDir);
+                const gStore = await initGraphStore(effectiveDataDir, effectiveProjectId);
 
                 const allObs = filterDashboardObservations(
                     await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }),
@@ -595,7 +594,7 @@ async function handleApi(
                 );
                 const skills = await getMiniSkillStore().loadByProject(effectiveProjectId);
 
-                const fullGraph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
+                const fullGraph = { entities: gStore.loadEntities(), relations: gStore.loadRelations() };
                 const scoped = scopeKnowledgeGraphToProject(fullGraph, allObs);
 
                 const graph = generateKnowledgeGraph({
@@ -848,8 +847,7 @@ async function handleApi(
 
                         // Sync: clean up graph entity references for this observation
                         try {
-                            await initGraphStore(effectiveDataDir);
-                            const gStore = getGraphStore();
+                            const gStore = await initGraphStore(effectiveDataDir, effectiveProjectId);
                             const prefix = `[#${obsId}] `;
                             const deletions: { entityName: string; observations: string[] }[] = [];
                             for (const entity of gStore.loadEntities()) {
@@ -865,8 +863,8 @@ async function handleApi(
                 }
 
                 if (apiPath === '/export') {
-                    await initGraphStore(effectiveDataDir);
-                    const fullGraph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
+                    const gStore = await initGraphStore(effectiveDataDir, effectiveProjectId);
+                    const fullGraph = { entities: gStore.loadEntities(), relations: gStore.loadRelations() };
                     const observations = filterDashboardObservations(
                         await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }),
                         effectiveProjectId,

package/src/integrations/registry.ts

@@ -72,7 +72,7 @@ export const MEMORIX_INTEGRATIONS: MemorixIntegration[] = [
     status: 'ready',
     install: 'memorix setup --agent grok --global',
     surfaces: ['hooks', 'AGENTS.md'],
-    note: 'Writes ~/.grok/hooks/memorix.json and leaves Grok MCP host-owned; setup does not write config.toml.',
+    note: 'Writes ~/.grok/hooks/memorix.json and leaves Grok MCP host-owned by default. Pass --mcp http to write [mcp_servers.memorix] in Grok config.toml.',
   },
   {
     agent: 'cursor',

package/src/memory/graph.ts

@@ -11,18 +11,21 @@
  */
 
 import type { Entity, Relation, KnowledgeGraph } from '../types.js';
-import { initGraphStore, getGraphStore } from '../store/graph-store.js';
+import { initGraphStore, type GraphSqliteStore } from '../store/graph-store.js';
 
 export class KnowledgeGraphManager {
   private entities: Entity[] = [];
   private relations: Relation[] = [];
   private projectDir: string;
+  private projectId: string;
+  private store: GraphSqliteStore | null = null;
   private initialized = false;
   /** Index: lowercase entity name → Entity for O(1) lookups */
   private entityIndex = new Map<string, Entity>();
 
-  constructor(projectDir: string) {
+  constructor(projectDir: string, projectId = '__default__') {
     this.projectDir = projectDir;
+    this.projectId = projectId;
   }
 
   /** Rebuild the entity name index */
@@ -36,10 +39,9 @@ export class KnowledgeGraphManager {
   /** Load graph from SQLite on first access */
   async init(): Promise<void> {
     if (this.initialized) return;
-    await initGraphStore(this.projectDir);
-    const store = getGraphStore();
-    this.entities = store.loadEntities();
-    this.relations = store.loadRelations();
+    this.store = await initGraphStore(this.projectDir, this.projectId);
+    this.entities = this.store.loadEntities();
+    this.relations = this.store.loadRelations();
     this.rebuildIndex();
     this.initialized = true;
   }
@@ -56,8 +58,8 @@ export class KnowledgeGraphManager {
 
   /** Persist current state to SQLite */
   private async save(): Promise<void> {
-    const store = getGraphStore();
-    store.replaceAll(this.entities, this.relations);
+    if (!this.store) throw new Error('[memorix] KnowledgeGraphManager not initialized');
+    this.store.replaceAll(this.entities, this.relations);
   }
 
   /** Create new entities (skip duplicates by name) */

package/src/memory/session.ts

@@ -616,7 +616,7 @@ export async function getSessionContext(
     let graphNeighbors: string[] = [];
     if (!reader && activeEntities.length > 0) {
       try {
-        const graphMgr = new KnowledgeGraphManager(projectDir);
+        const graphMgr = new KnowledgeGraphManager(projectDir, projectId);
         await graphMgr.init();
         const { relations } = await graphMgr.readGraph();
         const activeSet = new Set(activeEntities.map((n) => n.toLowerCase()));

package/src/sdk.ts

@@ -28,6 +28,7 @@ import type {
   ObservationReader,
   RetrievalQuality,
 } from './types.js';
+import path from 'node:path';
 import {
   canManageObservation,
   canReadObservation,
@@ -101,6 +102,9 @@ export interface ResolveResult {
   notFound: number[];
 }
 
+const activeSdkClients = new Map<string, number>();
+let activeSdkDataDir: string | null = null;
+
 /**
  * A lightweight, self-contained memory client for reading and writing
  * Memorix observations without MCP overhead.
@@ -124,6 +128,7 @@ export class MemoryClient {
   private _oramaStore!: typeof import('./store/orama-store.js');
   private _obsStore!: typeof import('./store/obs-store.js');
   private _freshness!: typeof import('./memory/freshness.js');
+  private _sdkRefRegistered = false;
 
   /** @internal — use createMemoryClient() instead */
   constructor(projectId: string, projectRoot: string, dataDir: string) {
@@ -147,6 +152,12 @@ export class MemoryClient {
    * Called by createMemoryClient(). Do not call directly.
    */
   async _init(silent: boolean): Promise<void> {
+    const normalizedDataDir = path.resolve(this._dataDir);
+    if (activeSdkDataDir && activeSdkDataDir !== normalizedDataDir) {
+      throw new Error(
+        '[memorix-sdk] Multiple active clients with different data directories are not supported in one process; use separate processes.',
+      );
+    }
     // Suppress logs if requested
     const originalError = console.error;
     if (silent) {
@@ -167,6 +178,9 @@ export class MemoryClient {
 
       // Prepare search index (hydrate Orama from SQLite)
       await this._observations.prepareSearchIndex();
+      activeSdkDataDir = normalizedDataDir;
+      activeSdkClients.set(normalizedDataDir, (activeSdkClients.get(normalizedDataDir) ?? 0) + 1);
+      this._sdkRefRegistered = true;
     } finally {
       if (silent) {
         console.error = originalError;
@@ -298,6 +312,16 @@ export class MemoryClient {
   async close(): Promise<void> {
     if (this._closed) return;
     this._closed = true;
+    const normalizedDataDir = path.resolve(this._dataDir);
+    const currentRefs = activeSdkClients.get(normalizedDataDir) ?? 0;
+    const remainingRefs = Math.max(0, currentRefs - (this._sdkRefRegistered ? 1 : 0));
+    if (remainingRefs > 0) {
+      activeSdkClients.set(normalizedDataDir, remainingRefs);
+      this._sdkRefRegistered = false;
+      return;
+    }
+    activeSdkClients.delete(normalizedDataDir);
+    if (activeSdkDataDir === normalizedDataDir) activeSdkDataDir = null;
     try {
       this._obsStore.resetObservationStore();
       await this._oramaStore.resetDb();

package/src/server/mcp-binding-store.ts

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { getDatabase } from '../store/sqlite-db.js';
 
+export const DEFAULT_MCP_BINDING_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
 export interface McpProjectBinding {
   handleId: string;
   projectId: string;
@@ -38,6 +40,7 @@ export class McpBindingStore {
 
   create(input: { projectId: string; projectRoot: string; dataDir: string; ttlMs?: number }): McpProjectBinding {
     const now = new Date();
+    const ttlMs = input.ttlMs ?? DEFAULT_MCP_BINDING_TTL_MS;
     const binding: McpProjectBinding = {
       handleId: `mxh_${randomUUID().replace(/-/g, '')}`,
       projectId: input.projectId,
@@ -45,7 +48,7 @@ export class McpBindingStore {
       dataDir: input.dataDir,
       createdAt: now.toISOString(),
       lastUsedAt: now.toISOString(),
-      ...(input.ttlMs && input.ttlMs > 0 ? { expiresAt: new Date(now.getTime() + input.ttlMs).toISOString() } : {}),
+      ...(ttlMs > 0 ? { expiresAt: new Date(now.getTime() + ttlMs).toISOString() } : {}),
     };
     this.requireDb().prepare(`
       INSERT INTO mcp_bindings (handle_id, project_id, project_root, data_dir, created_at, last_used_at, expires_at)
@@ -69,8 +72,16 @@ export class McpBindingStore {
     const binding = this.get(handleId);
     if (!binding) return undefined;
     const lastUsedAt = new Date().toISOString();
-    this.requireDb().prepare(`UPDATE mcp_bindings SET last_used_at = ? WHERE handle_id = ?`).run(lastUsedAt, handleId);
-    return { ...binding, lastUsedAt };
+    const expiresAt = new Date(Date.now() + DEFAULT_MCP_BINDING_TTL_MS).toISOString();
+    this.requireDb().prepare(`UPDATE mcp_bindings SET last_used_at = ?, expires_at = ? WHERE handle_id = ?`).run(lastUsedAt, expiresAt, handleId);
+    return { ...binding, lastUsedAt, expiresAt };
+  }
+
+  cleanupExpired(now = Date.now()): number {
+    const result = this.requireDb().prepare(
+      `DELETE FROM mcp_bindings WHERE expires_at IS NOT NULL AND expires_at <= ?`,
+    ).run(new Date(now).toISOString());
+    return Number(result.changes ?? 0);
   }
 
   /** Reuse the most recent valid extension handle for a verified project root. */

package/src/server.ts

@@ -364,7 +364,7 @@ export async function createMemorixServer(
     const store = getObservationStore();
     console.error(`[memorix] ObservationStore backend: ${store.getBackendName()}, generation: ${store.getGeneration()}`);
   }
-  let graphManager = new KnowledgeGraphManager(projectDir);
+  let graphManager = new KnowledgeGraphManager(projectDir, project.id);
   if (!deferProjectRuntimeInit) {
     await graphManager.init();
     await initObservations(projectDir);
@@ -378,7 +378,7 @@ export async function createMemorixServer(
     await initObservationStore(projectDir);
     await initMiniSkillStore(projectDir);
     await initSessionStore(projectDir);
-    graphManager = new KnowledgeGraphManager(projectDir);
+    graphManager = new KnowledgeGraphManager(projectDir, project.id);
     await graphManager.init();
     await initObservations(projectDir);